v2 Upload Flow

WORK IN PROGRESS

Overview

The goal of this document is to give an overview of API interactions that occur when a SafePaths mobile user uploads their data to the SafePlaces API within the context of a contact tracing interview.

Flow Overview

Case Creation

Contact tracer creates a new case within the SafePaths web UI. At this time the case is assigned a unique caseId, which is returned to the web UI in the response.

Private WebUI Service
Endpoint: POST /organization/case (SPL API Specification v1 (For MVP1) )
Write to Private DB

Access Code Creation

Contact tracer creates an access code which can be used by the SafePlaces mobile app to upload points of concern. At the time of writing there is no UI design for initiating access code creation manually, so for now the web UI will create and display an access code automatically after creating the case. The code is generated according to SPL Token Exchange, and only exists for 1 hour. The contact tracer communicates this code to the user verbally over the phone.

Private WebUI Service
Endpoint: POST /access-code (SPL API Specification v1 (For MVP1))
Write to Ingest/Upload DB

Access Code Validation

The user will input the accessCode into the SafePaths app. An API request will be made to this endpoint. The endpoint returns a boolean indicating whether or not the accessCode exists and is valid.

Ingest/Upload Service
Endpoint: GET /access-code/valid (https://pathcheck.atlassian.net/wiki/spaces/SA/pages/73924822/SPL+API+Specification+v1+For+MVP1#GET-%2Faccess-code%2Fvalid%2F%7BaccessCode%7D )
Read from Ingest/Upload DB

User Consent

The user consents to the HA’s terms of service after the access code is confirmed to be valid. We record the user’s consent and invalidate the accessCode record (set invalidatedAt timestamp) if the user did not consent to the terms of service.

Ingest/Upload Service
Endpoint: POST /consent (https://pathcheck.atlassian.net/wiki/spaces/SA/pages/73924822/SPL+API+Specification+v1+For+MVP1#POST-%2Fconsent )
Write to Ingest/Upload DB

Data Upload

User data (points of concern) are posted to the endpoint along with the accessCode. Validation on the accessCode occurs once more and then we persist the provided data, as well as persisting the access code used for upload. The upload response contains a unique uploadId that can be subsequently be used to delete the uploaded data. The access code is invalidated upon success.

Ingest/Upload Service
Endpoint: POST /upload (https://pathcheck.atlassian.net/wiki/spaces/SA/pages/73924822/SPL+API+Specification+v1+For+MVP1#POST-%2Fupload )
Write to Ingest/Upload DB

Case ↔︎ Data Association

The SafePlaces frontend application calls to POST /cases/points (SPL API Specification v1 (For MVP1) ), providing both the accessCod and the caseId. Repeated calls may be made until a terminal status is reached:

If the access code is invalid, an appropriate error status code is returned and the upload is aborted.
If the user declined the ToS, an appropriate error status code is returned and the upload is aborted.
If upload has completed successfully, the endpoint returns the points of concern that were uploaded from the SafePaths app for the given access token.

On the backend, the points will have been saved to the Private DB, and interaction with the Ingest/Upload DB is complete for this case.

Private WebUI Service
Read from Ingest/Upload DB
Write to Private DB

Displaying Points for the Case

The SafePlaces frontend application can now retrieve the list of points for the case from GET /case/points (https://pathcheck.atlassian.net/wiki/spaces/SA/pages/73924822/SPL+API+Specification+v1+For+MVP1#GET-%2Fcase%2F%7BcaseId%7D%2Fpoints ), for display in the UI.

Private WebUI Service
Read from Private DB