Cwa-documentation: [Fix 1.8?] Do you plan to migrate to API v1.5? If so, when?

Created on 10 Jul 2020 · 11Comments · Source: corona-warn-app/cwa-documentation

What is missing

Google has modified their API documentation to include v1.5 (and hints about later versions as well).
Please explain your migration plans to these new versions.

Why should it be included

Many users are very interested in the specific details of how cwa works, how it estimates risk, and so on.
The API now offers different options, e.g. how to calculate risk, and what information can be made available to the user when a match was found.
The plans and reasons for the decisions of RKI regarding migration to the new version of the API should be made public.

Internal Tracking ID: EXPOSUREAPP-1914

documentation enhancement mirrored-to-jira

Source

mh-

👍5 ❤2

Most helpful comment

Here's a summary of how I understand these API changes:

API v1.5 will be rolled out to Android devices via updates of Google Play Services. To iPhones, it will be probably rolled out via a new iOS version, but Apple has not publicly announced this yet.
In API v1.5, there are 2 modes:
- v1 mode:
- completely backward compatible to the current setup (which they call v1.1)
- some "non-breaking changes" from API v1.5 will be also available in this mode, e.g. TEK of current day will be released (with shortened validity) and a new TEK will be generated (i.e. potentially multiple TEKs for one day), and more DK submission options --> this would help a lot for https://github.com/corona-warn-app/cwa-backlog/issues/2
- ExposureWindow mode:
- This moves the risk calculation part from the API to the app, and gives a lot more details about each matched "risk encounter" to the app: Instead of doing the risk calculation based on ExposureConfiguration, the API now gives a list of ExposureWindow objects to the app. Each ExposureWindow comes with a list of ScanInstance objects, which contain relative timing info (summing up to max. 30 minutes) and details about the RF attenuation of a group of scans.
- Exact timestamps of the ExposureWindows are not made available to the app, so the app will still only know the day, not the exact time, when an exposure occurred.
- The Transmission Risk Level (the part of the current CWA risk calculation that has been documented in detail) is _not_ used anymore. Instead, an "infectiousness of STANDARD or HIGH, computed from its days since onset of symptoms using a configurable mapping" would probably replicate this concept, but is "planned for a future release but not implemented in v1.5". A reportType like CONFIRMED_CLINICAL_DIAGNOSIS could be attached to Diagnosis Keys and then used for the risk estimation.
- The app could determine that a device has not yet been updated to API v1.5 by catching API_NOT_CONNECTED exception.

mh- on 11 Jul 2020

🚀6

All 11 comments

Here's a summary of how I understand these API changes:

API v1.5 will be rolled out to Android devices via updates of Google Play Services. To iPhones, it will be probably rolled out via a new iOS version, but Apple has not publicly announced this yet.
In API v1.5, there are 2 modes:
- v1 mode:
- completely backward compatible to the current setup (which they call v1.1)
- some "non-breaking changes" from API v1.5 will be also available in this mode, e.g. TEK of current day will be released (with shortened validity) and a new TEK will be generated (i.e. potentially multiple TEKs for one day), and more DK submission options --> this would help a lot for https://github.com/corona-warn-app/cwa-backlog/issues/2
- ExposureWindow mode:
- This moves the risk calculation part from the API to the app, and gives a lot more details about each matched "risk encounter" to the app: Instead of doing the risk calculation based on ExposureConfiguration, the API now gives a list of ExposureWindow objects to the app. Each ExposureWindow comes with a list of ScanInstance objects, which contain relative timing info (summing up to max. 30 minutes) and details about the RF attenuation of a group of scans.
- Exact timestamps of the ExposureWindows are not made available to the app, so the app will still only know the day, not the exact time, when an exposure occurred.
- The Transmission Risk Level (the part of the current CWA risk calculation that has been documented in detail) is _not_ used anymore. Instead, an "infectiousness of STANDARD or HIGH, computed from its days since onset of symptoms using a configurable mapping" would probably replicate this concept, but is "planned for a future release but not implemented in v1.5". A reportType like CONFIRMED_CLINICAL_DIAGNOSIS could be attached to Diagnosis Keys and then used for the risk estimation.
- The app could determine that a device has not yet been updated to API v1.5 by catching API_NOT_CONNECTED exception.

mh- on 11 Jul 2020

🚀6

Our development team is already aware of the new API version and has already discussed some of the aspects. The way forward is currently under investigation. Once we have a decision, it will - of course - be documented accordingly.

Mit freundlichen Grüßen/Best regards,
SW
Corona Warn-App Open Source Team

SebastianWolf-SAP on 11 Jul 2020

👍3 👀2

Roll out of v1.5 has not been completed yet!
https://github.com/google/exposure-notifications-android/issues/42

gitbrueck on 15 Jul 2020

Apple removed limits on number of files submitted, and only limits number of calls from iOS version 13.6: https://developer.apple.com/documentation/exposurenotification/enmanager/3586331-detectexposures

Apps can’t make more than 15 calls to this API in a 24-hour period, but may submit multiple files in each API call.
In iOS 13.5 and earlier, apps can only submit 15 key files per 24 hour period, regardless of the number of API calls made.

So it would be possible to achieve refresh of exposure status every 2 hours on iPhone and every 4 hours on Android.

kbobrowski on 22 Jul 2020

👍3

Yep, things are improving. Hope that most/all people will upgrade to 13.6... We'll ask our product management if and how these changes can be integrated as soon as possible.

Mit freundlichen Grüßen/Best regards,
SW
Corona Warn-App Open Source Team

SebastianWolf-SAP on 22 Jul 2020

👍3

Hello @mh-,

to keep you and the community in the loop, I reached out to @hermesmar .
We will discuss internally, if and how we can let the community know about migration decisions and reasons so that it is easier for the community to follow up.

Thanks,
LMM

Corona-Warn-App Open Source Team