SPL API Specification v1 (For MVP1)
- Satoshi Kawase
- Daniel McCoy
- Satoshi Kawase
- 1 References
- 2 Public endpoints
- 3 Private endpoints
- 3.1 IMPLEMENTED: POST /login
- 3.2 Confirmed: POST /access-code
- 3.3 IMPLEMENTED: GET /organization
- 3.4 IMPLEMENTED: GET /organization/configuration
- 3.5 IMPLEMENTED: PUT /organization/configuration
- 3.6 IMPLEMENTED: GET /organization/cases
- 3.7 IMPLEMENTED: POST /organization/case
- 3.8 IMPLEMENTED: PUT /case
- 3.9 IMPLEMENTED: DELETE /organization/case
- 3.10 IMPLEMENTED: GET /case/points
- 3.11 Confirmed: POST /case/points
- 3.12 IMPLEMENTED: POST /case/point
- 3.13 Implemented: POST /case/consent-to-publishing
- 3.14 IMPLEMENTED: POST /case/stage
- 3.15 IMPLEMENTED: POST /cases/publish
- 3.16 IMPLEMENTED: PUT /case/point
- 3.17 IMPLEMENTED: DELETE /case/point
References
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
Code | Description |
200 | Successful Request application/json
{
"valid": true
} |
403 | Invalid Access Code |
404 | Not Found |
500 | Internal Server error |
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.
Parameters
No parameters
Request body
{
"consent": true/false,
"accessCode": "123456"
}Responses
Code | Description |
200 | Successful Request |
403 | Invalid Access Code |
404 | Not Found |
500 | Internal Server error |
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 Design for MVP1 HA JSON Changes SPL Token ExchangeMVP1: App to SPL Flow
Parameters
No parameters
Request body
application/json
Example Value
Responses
Code | Description |
201 | Created application/json
|
400 | Invalid Input |
403 | Invalid Access Code |
404 | Not Found |
451 | Consent Not Granted |
500 | Internal Server error |
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
Responses
Code | Description | Response |
200 | The user was found and the | |
401 | There is no user with the | |
500 | Internal server error. |
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
Code | Description |
201 | OK application/json
|
400 | Invalid request |
401 | Unauthorized Client |
500 | Internal Server error |
IMPLEMENTED: GET /organization
Returns information about the organization associated with the requesting user.
Parameters
No parameters
Request body
No body
Responses
Code | Description |
200 | OK application/json
|
400 | Invalid request |
403 | Lacks sufficient authority for operation |
500 | Internal Server error |
IMPLEMENTED: GET /organization/configuration
Returns the configuration of the organization associated with the requesting user.
Parameters
No parameters
Request body
No Body
Responses
Code | Description |
200 | OK application/json
|
400 | Invalid request |
403 | Lacks sufficient authority for operation |
500 | Internal Server error |
IMPLEMENTED: PUT /organization/configuration
Updates the configuration of the organization.
Parameters
No parameters
Request body
application/JSON
Example Value
Responses
Code | Description |
200 | OK application/json
|
400 | Invalid request |
403 | Lacks sufficient authority for operation |
500 | Internal Server error |
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
Code | Description |
200 | OK application/json
|
400 | Invalid request |
403 | Lacks sufficient authority for operation |
500 | Internal Server error |
IMPLEMENTED: POST /organization/case
Creates a new case, and associates it with the organization of logged in user.
See MVP1: App to SPL Flow, SPL Data States (For MVP1)
Parameters
No parameters
Request body
No parameters
Responses
Code | Description |
200 | Created application/json
|
400 | Invalid request |
403 | Lacks sufficient authority for operation |
500 | Internal Server error |
IMPLEMENTED: PUT /case
Updates a case (currently only supports updating of case’s extern id)/
Parameters
No parameters
Request body
application/JSON
Example Value
Responses
Code | Description |
200 | Created application/json
|
400 | Invalid request |
403 | Lacks sufficient authority for operation |
500 | Internal Server error |
IMPLEMENTED: DELETE /organization/case
Delete case record
Parameters
No parameters
Request body
application/JSON
Example Value
Responses
Code | Description |
200 | Case deleted |
400 | Invalid request |
403 | Lacks sufficient authority for operation |
500 | Internal Server error |
IMPLEMENTED: GET /case/points
Returns all points of concern for the provided case.
Parameters
No parameters
Request body
application/JSON
Example Value
Responses
Code | Description |
200 | Return points of concern associated with the case. application/json
|
400 | Invalid request |
403 | Lacks sufficient authority for operation |
500 | Internal Server error |
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.
Parameters
No parameters
Request body
application/JSON
Example Value
Responses
Code | Description |
200 | Returns the points of concern now associated with the case. application/json
|
202 | Upload In Progress |
400 | Invalid request |
401 | Unauthorized Client |
403 | Invalid Access Code |
451 | Consent Not Granted |
500 | Internal Server error |
IMPLEMENTED: POST /case/point
Creates a new point of concern to be associated with the case.
Parameters
No parameters
Request body
application/JSON
Example Value
Responses
Code | Description |
200 | Returns the created point of concern application/json
|
400 | Invalid request |
403 | Lacks sufficient authority for operation |
500 | Internal Server error |
Implemented: 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
Responses
Code | Description |
|---|---|
200 | |
400 | Invalid request |
403 | Lacks sufficient authority for operation |
500 | Server Error |
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
Responses
Code | Description |
|---|---|
200 | |
400 | Invalid request |
403 | Lacks sufficient authority for operation |
500 | Server Error |
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
Responses
Code | Description |
|---|---|
200 | |
400 | Invalid request |
403 | Lacks sufficient authority for operation |
500 | Server Error |
IMPLEMENTED: PUT /case/point
Updates an existing point of concern
Parameters
No parameters
Request body
application/JSON
Example Value
Responses
Code | Description |
200 | Point was updated application/json
|
400 | Invalid request |
403 | Lacks sufficient authority for operation |
500 | Server Error |
IMPLEMENTED: DELETE /case/point
Deletes the point of concern having the ID corresponding with the pointID param.
Parameters
No parameters
Request body
application/JSON
Example Value
Responses
Code | Description |
200 | Point was deleted |
400 | Invalid request |
403 | Lacks sufficient authority for operation |
500 | Internal Server error |
The access code will have to be a query param or be embedded in the url
Unless we change this to a POST request
It was a path param but to Peter’s recommendation was not to include identifiers in network log requests. query param would be the same, no?
(valid concern, but imho a bit too paranoid)
@Daniel McCoy you’re call. We could switch to POST or we could just anger the internet gods and include request body in GET.
Whatever we decide probably makes sense to stay consistent with other GET requests
Tbh I’ve never seen a request body in a GET request. Just did a quick Google search and it looks like it’s valid, but undocumented in the HTTP specification.
What @Aiyan Jiang said. But Let’s just have it in the body for consistency’s sake. Not a hill I’m willing to die on.