Closed jshslsky closed 11 years ago
jshslsky
commented
11 years ago We decided that it would be best to document the write API within this issue. We can discuss with the architecture working group whether write is required or optional or even necessary at all.
jojenki
commented
11 years ago Path /omh/v0.1/write
Parameters
| Key | Description | Required |
|---|---|---|
| requester | A string representing the application that is making this request. In the next version of the specification, we should probably get rid of this and just use the User-Agent header. | true |
| payload_id | The payload ID to which this data belongs. | true | payload_version | The version of the payload to which this data belongs | true |
| data | A JSON array of JSON objects representing the data. Each JSON object should have two sections, "metadata" and "data". The "metadata" is based on the "id", "timestamp", and "location" fields and should conform to whatever the registry dictates. The "data" should conform to the schema as provided by the registry. | true |
If the user is not authenticated, a HTTP 401 will be returned; however, a HTTP WWW-Authenticate header will not be. This goes against the specification but appears to be a somewhat common thing to do. The thing is that the Authenticate header is relatively unused anymore and 401 tells the user exactly what the problem is. A 403 doesn't work because it specifically says that, "authorization will not help and the request SHOULD NOT be repeated." A 400 seems a little too ambiguous, and, technically, there may not have been anything wrong with the request. The user is simply missing authentication credentials, or the credentials were not sufficient.
If there is any problem with the data, from the entire text not being valid JSON to an individual point having invalid metadata or data that does not conform to its schema, the entire upload will be rejected with a HTTP 400.
Otherwise, unless another HTTP status code is more appropriate, a 204 (no content) status code is returned.
As a complement to read, we need write. This is a use case originally driven by Anne: device manufacturers and app developers need an Open mHealth-compliant way to upload data to any omh DSU. To this end, our testing use cases are MoodMap and PAM, both of which are currently hacked into ohmage using campaigns.
The write API will support uploads of payloads that a given DSU's registry includes. The payloads will need to be validated for Concordia schema compliance and then persisted and linked to the uploading user's account.