References

• MVP1: App to SPL Flow

• SafePaths <-> SafePlaces Data Flow Overview

• Open API 3.0 version on Apiary

• https://pathcheck.atlassian.net/wiki/spaces/TEST/pages/81231882/Hashing+of+GPS+points+-+Design#Safe-Places-Publishing-of-Data

• SPL Token Exchange

• https://pathcheck.atlassian.net/wiki/spaces/TEST/pages/61112371/Design%2Bfor%2BMVP1%2BHA%2BJSON%2BChanges

• https://pathcheck.atlassian.net/wiki/pages/createpage.action?spaceKey=SA&title=Public+vs.+Private+Instances+of+SafePlaces+API&linkCreation=true&fromPageId=73924822

• SafePlaces API Architecture

• SPL Data States (For MVP1)

• SPL UI Protype (Figma)

Public endpoints

IMPLEMENTED: GET /access-code/valid

Determines whether an access code is valid and if it can be used to perform an /upload API call.

See SPL Token ExchangeMVP1: App to SPL Flow

Parameters

No parameters

Request body

{
  "accessCode": "123456"
}

Responses

{
  "valid": true
}

IMPLEMENTED: POST /consent

Logs user consent to health authority’s terms of service. Invalidates the accessCode that is passed in the payload if consent is false.

See MVP1: App to SPL Flow

Parameters

No parameters

Request body

{
  "consent": true/false,
  "accessCode": "123456"
}

Responses

IMPLEMENTED: POST /upload

Accepts SAFE PATHS data upload from the user. Access code sent in body must match an access code created in a POST /access-code call. The uploadId returned may be used by clients to purge data from this upload at a later time.

see https://pathcheck.atlassian.net/wiki/spaces/TEST/pages/61112371/Design%2Bfor%2BMVP1%2BHA%2BJSON%2BChanges SPL Token ExchangeMVP1: App to SPL Flow

Parameters

No parameters

Request body

application/json

• Example Value

{
  "accessCode": "123456",
  "concernPoints": [
    {
      "longitude": 14.91328448,
      "latitude": 41.24060321,
      "time": 1589117739000,
      "hash": "87e916850d4def3c"
    }
  ]
}

Responses

{
  "uploadId": "42963a2f-9bd8-4ade-a713-3106020c1942"
}

Private endpoints

IMPLEMENTED: POST /login

Authenticates the user and responds with a JWT that can be used to access protected endpoints.

See SPL Token Exchange.

Parameters

No parameters

Request body

application/json

• Example Value

{
  "username": "admin",
  "password": "admin"
}

Responses

{
  "token": "eyABCD4321JIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImlhdCI6MTU5MDE1MjIzMCwiZXhwIjoxNTkwMTU1ODMwfQ.QUK4ybt971yQiqUT-HTVPh6VsRkxM2wEKTpTYifY3Uw"
}

{
  "message": "Invalid credentials."
}

CONFIRMED: POST /access-code

Returns a new access code that clients can use to upload data via the public endpoints above. The code should remain valid for 1 hour.

See SPL Token Exchange.

Parameters

No parameters

Request body

No body

Responses

{
  "accessCode": "123456"
}

IMPLEMENTED: GET /organization

Returns information about the organization associated with the requesting user.

Parameters

No parameters

Request body

No body

Responses

{
  "organizationId": 777,
  "name": "Same Health Authority",
  "completedOnBoarding": true
}

IMPLEMENTED: GET /organization/configuration

Returns the configuration of the organization associated with the requesting user.

See SPL UI Protype (Figma)

Parameters

No parameters

Request body

No Body

Responses

{
  "name": "Same Health Authority",
  "notificationThresholdPercent": 66,
  "notificationThresholdCount": 6,
  "daysToRetainRecords": 14,
  "regionCoordinates": { 
    "ne": { "latitude": 20.312764055951195, "longitude": -70.45445121262883}, 
    "sw": { "latitude": 17.766025040122642, "longitude": -75.49442923997258}
  },
  "apiEndpointUrl": "https://s3.aws.com/bucket_name/safepaths.json",
  "referenceWebsiteUrl": "http://cdc.gov",
  "infoWebsiteUrl": "http://cdc.gov"
}

IMPLEMENTED: PUT /organization/configuration

Updates the configuration of the organization.

See SPL UI Protype (Figma)

Parameters

No parameters

Request body

application/JSON

• Example Value

{
  "organizationId": 73,
  "name": "Same Health Authority",
  "notificationThresholdPercent": 66,
  "notificationThresholdCount": 6,
  "daysToRetainRecords": 14,
  "regionCoordinates": { 
    "ne": { "latitude": 20.312764055951195, "longitude": -70.45445121262883}, 
    "sw": { "latitude": 17.766025040122642, "longitude": -75.49442923997258}
  },
  "apiEndpointUrl": "https://s3.aws.com/bucket_name/safepaths.json",
  "referenceWebsiteUrl": "http://cdc.gov",
  "infoWebsiteUrl": "http://cdc.gov"
}

Responses

{
  "organizationId": 73,
  "name": "Same Health Authority",
  "notificationThresholdPercent": 66,
  "notificationThresholdCount": 6,
  "daysToRetainRecords": 14,
  "regionCoordinates": { 
    "ne": { "latitude": 20.312764055951195, "longitude": -70.45445121262883}, 
    "sw": { "latitude": 17.766025040122642, "longitude": -75.49442923997258}
  },
  "apiEndpointUrl": "https://s3.aws.com/bucket_name/safepaths.json",
  "referenceWebsiteUrl": "http://cdc.gov",
  "infoWebsiteUrl": "http://cdc.gov"
}

IMPLEMENTED: GET /organization/cases

Gets a list of case records for the organization

See SPL UI Protype (Figma), SPL Data States (For MVP1)

Parameters

No parameters

Request body

No body

Responses

{
  "cases": [
    {
      "caseId": 12,
      "state": "unpublished",
      "externalId": "an_external_id",
      "updatedAt": "2020-05-21T18:25:43.511Z",
      "expiresAt": "2020-05-30T18:25:43.511Z"
    },
    {
      "caseId": 13,
      "state": "staging",
      "externalId": "an_external_id",
      "updatedAt": "2020-05-21T18:25:43.511Z",
      "expiresAt": "2020-05-30T18:25:43.511Z"
    },
    {
      "caseId": 14,
      "state": "published",
      "externalId": "an_external_id",
      "updatedAt": "2020-05-21T18:25:43.511Z",
      "expiresAt": "2020-05-30T18:25:43.511Z"
    }
  ]
}

CONFIRMED: POST /organization/case

Creates a new case, and associates it with the organization.

See MVP1: App to SPL Flow, SPL Data States (For MVP1)

Parameters

No parameters

Request body

application/JSON

• Example Value

{
      "organizationId" : 777
}

Responses

{
  "caseId": 1,
  "state": "unpublished",
  "externalId": "an_external_id",
  "expiresAt": "2020-05-30T18:25:43.511Z",
  "updatedAt": "2020-05-21T18:25:43.511Z",
}

CONFIRMED: PUT /case

Updates a case (currently only supports updating of case’s extern id)/

Parameters

No parameters

Request body

application/JSON

• Example Value

{
      "caseId" : 23,
      "externalId": "an_external_id"
}

Responses

{
  "caseId": 23,
  "state": "unpublished",
  "externalId": "an_external_id",
  "expiresAt": "2020-05-30T18:25:43.511Z",
  "updatedAt": "2020-05-21T18:25:43.511Z",
}

IMPLEMENTED: DELETE /case

Delete case record

See SPL UI Protype (Figma)

Parameters

No parameters

Request body

application/JSON

• Example Value

{
      "caseId" : 12
}

Responses

IMPLEMENTED: GET /case/points

Returns all points of concern for the provided case.

See SPL UI Protype (Figma)

Parameters

No parameters

Request body

application/JSON

• Example Value

{
      "caseId": 12
}

Responses

{
  "concernPoints": [
    {
      "pointId": 232,
      "longitude": 14.91328448,
      "latitude": 41.24060321,
      "time": "2020-05-30T18:25:43.511Z"
    }
  ]
}

CONFIRMED: POST /case/points

Associates the results of a previous upload with a case. accessCode should match a code returned from POST /access-code, and caseId should be from a call to POST /organization/cases.

See SPL UI Protype (Figma)

Parameters

No parameters

Request body

application/JSON

• Example Value

{
  "accessCode": "123456",
  "caseId": 12
}

Responses

{
  "concernPoints": [
    {
      "pointId": 232,
      "longitude": 14.91328448,
      "latitude": 41.24060321,
      "time": "2020-05-30T18:25:43.511Z"
    }
  ]
}

IMPLEMENTED: POST /case/point

Creates a new point of concern to be associated with the case.

See SPL UI Protype (Figma)

Parameters

No parameters

Request body

application/JSON

• Example Value

{
      "caseId": 12,
      "point": {
        "longitude": 14.91328448,
        "latitude": 41.24060321,
        "time": "2020-05-30T18:25:43.511Z"
        }
}

Responses

{
  concernPoint: {
    pointId: 280,
    longitude: 14.91328448,
    latitude: 41.24060321,
    time: '2020-05-01T18:25:43.511Z'
  }
}

CONFIRMED: POST /case/consent-to-publishing

Captures user consent to having their data published in the aggregated anonymized JSON file that is available to public.

Parameters

No parameters

Request body

application/JSON

• Example Value

{
      "caseId" : 12
}

Responses

{
  "caseId": 14,
  "updatedAt": "2020-05-21T18:25:43.511Z",
  "state": "staging",
  "externalId": "an_external_id",
  "expiresAt": "2020-05-30T18:25:43.511Z"
}

IMPLEMENTED: POST /case/stage

Updates the state of the case from unpublished to staging.

See SPL Data States (For MVP1)

Parameters

No parameters

Request body

application/JSON

• Example Value

{
      "caseId" : 14
}

Responses

{
  "case": {
    "caseId": 14,
    "state": "staging",
    "externalId": "an_external_id",
    "updatedAt": "2020-05-21T18:25:43.511Z",
    "expiresAt": "2020-05-30T18:25:43.511Z"
  }
}

IMPLEMENTED: POST /cases/publish

Moves the state of the cases from staging to published and generates JSON file containing aggregated anonymized points of concern data. JSON file is then pushed to the endpoint responsible for hosting the published data (this functionality is implemented by HA).

See SPL Data States (For MVP1)

Parameters

No parameters

Request body

application/JSON

• Example Value

{
      "caseIds" : [12, 13, 14]
}

Responses

{
  cases: {
      {
      "caseId": 14,
      "updatedAt": "2020-05-21T18:25:43.511Z",
      "state": "published",
      "externalId": "an_external_id",
      "expiresAt": "2020-05-30T18:25:43.511Z"
    },
    {
      "caseId": 15,
      "updatedAt": "2020-05-21T18:25:43.511Z",
      "externalId": "an_external_id",
      "state": "published",
      "expiresAt": "2020-06-30T18:25:43.511Z"
    },
    {
      "caseId": 16,
      "updatedAt": "2020-05-21T18:25:43.511Z",
      "state": "published",
      "externalId": "an_external_id",
      "expiresAt": "2020-07-30T18:25:43.511Z"
    }
  }
}

IMPLEMENTED: PUT /point

Updates an existing point of concern

See SPL UI Protype (Figma)

Parameters

No parameters

Request body

application/JSON

• Example Value

{
      "pointId" : 123,
      "longitude": 12.91328448,
      "latitude": 39.24060321,
      "time": "2020-05-21T18:25:43.511Z"
}

Responses

{
  "point": {
    "pointId": 123,
    "longitude": 12.91328448,
    "latitude": 39.24060321,
    "time": "2020-05-21T18:25:43.511Z"
  }
}

IMPLEMENTED: DELETE /point

Deletes the point of concern having the ID corresponding with the pointID param.

See SPL UI Protype (Figma)

Parameters

No parameters

Request body

application/JSON

• Example Value

{
      "pointId" : 123
}

Responses