This repository has been archived by the owner on Apr 29, 2021. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 17
DSU API 0.1
joshuaselsky edited this page Mar 21, 2013
·
16 revisions
This documentation is for historical purposes only. The specification described here is out of date and no longer in use. Please see the 1.0 documentation and check the Road Map for more details.
The URI is omh/v0.1/registry/read.
The registry provides the definitions for the payloads available from a given DSU.
The only allowed HTTP method is GET.
| Name | Description | Required |
|---|---|---|
| payload_id | An Open mHealth payload ID. Limits the definitions returned to only those with this payload_id. If this parameter is not provided, the default is to return the definitions for all of the payload IDs. | no |
| payload_version | A number. Limits the definitions returned to only those with this version number. If this parameter is not provided, the default is to return the definitions for all versions. Normally used in conjunction with the payload_id to retrieve a specification definition; however if used without the payload_id parameter, the results will contain any definition with the provided version | no |
| num_to_skip | A number. Causes the API to return results starting after the number. | no |
| num_to_return | A number. Overrides the default page size. If this value is greater than the default, the request may be rejected or the server may limit the number of definitions returned to the default page size. | no |
Each registry entry is a payload ID and version pair. The results should be ordered. The ordering is not defined by this specification, but it must be consistent between requests for paging reasons. The maximum number of entries should not exceed the maximum page size of 100.
The response is a JSON array of JSON objects. Each JSON object is a registry entry and has the following fields.
| Key | JSON type | Description |
|---|---|---|
| payload_id | string | The ID for this definition. |
| payload_version | number | The version of this definition |
| local_tz_authoritative | boolean | Whether or not the time zone in the timestamp returned for each data point accurately reflects the user’s time zone at the moment the point was generated. |
| summarizable | boolean | Whether or not the “summarize” parameter is valid when reading data from this ID-version pair. |
| chunk_size | number | The maximum number of data points that may be read from this ID-version pair in a single request. |
| payload_definition | object | A Concordia schema that defines the structure for each data point returned for this ID-Version pair. |
Example HTTP request header
POST /app/omh/v0.1/registry/read HTTP/1.1
User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
Host: sc.omh.io
Accept: */*
Content-Length: 0
Content-Type: application/x-www-form-urlencoded
Example HTTP response header
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Expires: Fri, 5 May 1995 12:00:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
Content-Type: application/json
Transfer-Encoding: chunked
Date: Thu, 08 Nov 2012 00:45:27 GMT
Example HTTP response content
[
{
"chunk_size":2000,
"local_tz_authoritative":true,
"summarizable":false,
"payload_id":"omh:ohmage:observer:edu.ucla.cens.Mobility:error",
"payload_version":"2012061300",
"payload_definition":{
"type":"object",
"doc":"Only requires the user's mode, which must be 'ERROR'.",
"schema":[
{
"name":"mode",
"type":"string",
"doc":"The user's mode."
}
]
}
},
{
"chunk_size":2000,
"local_tz_authoritative":true,
"summarizable":false,
"payload_id":"omh:ohmage:observer:edu.ucla.cens.Mobility:extended",
"payload_version":"2012050700",
"payload_definition":{
"type":"object",
"doc":"Contains the user's mode as well as the sensor data.",
"schema":[
{
"name":"mode",
"type":"string",
"doc":"The user's mode."
},
{
"name":"speed",
"type":"number",
"doc":"The user's speed in the last minute.",
"optional":true
},
{
"name":"accel_data",
"type":"array",
"schema":{
"type":"object",
"doc":"A single accelerometer reading.",
"schema":[
{
"name":"x",
"type":"number",
"doc":"The x-component of the accelerometer reading."
},
{
"name":"y",
"type":"number",
"doc":"The y-component of the accelerometer reading."
},
{
"name":"z",
"type":"number",
"doc":"The z-component of the accelerometer reading."
}
]
},
"doc":"An array of the accelerometer readings over the last minute."
},
{
"name":"wifi_data",
"type":"object",
"doc":"A WiFi reading from the last minute.",
"schema":[
{
"name":"time",
"type":"number",
"doc":"The time this data was recorded."
},
{
"name":"timezone",
"type":"string",
"doc":"The time zone of the device when this data was recorded."
},
{
"name":"scan",
"type":"array",
"schema":{
"type":"object",
"doc":"A single access point's information.",
"schema":[
{
"name":"ssid",
"type":"string",
"doc":"The access point's SSID."
},
{
"name":"strength",
"type":"number",
"doc":"The strength of the signal from the access point."
}
]
},
"doc":"The scan of WiFi information."
}
]
}
]
}
},
{
"chunk_size":2000,
"local_tz_authoritative":true,
"summarizable":false,
"payload_id":"omh:ohmage:observer:edu.ucla.cens.Other",
"payload_version":"2012050700",
"payload_definition":{
"type":"object",
"doc":"Only requires the user's mode, which must be 'ERROR'.",
"schema":[
{
"name":"mode",
"type":"string",
"doc":"The user's mode."
}
]
}
}
]
Authentication provides a way for users to authenticate themselves. In return, they will get a token that can be used in subsequent read requests. Unfortunately, there is no way for a third-party system to authenticate themselves, which means that the user must generate the token on their own and then provide it to the third-party application.
The URI is omh/v0.1/authenticate.
The only allowed HTTP method is POST.
The following parameters are available for the API call.
| Name | Description | Required |
|---|---|---|
| user | The user's username. | yes |
| password | The user's password. | yes |
| requester | A string representing the requester that is making this call. The requesters username. | yes |
| expires | The number of milliseconds that the token should last. | yes |
A HTTP 400 status code indicates that the request was malformed or missing something. A HTTP 401 indicates that the request was fine, but that the credentials were incorrect. A HTTP 200 will be returned otherwise.
The response is a JSON object with the following fields.
| Key | JSON type | Description |
|---|---|---|
| auth_token | string | The authentication token that must be used for subsequent calls. |
| expires | string | A W3C ISO-8601-formatted date-time. The date-time when this token expires. |
Example HTTP request header:
POST /app/omh/v1.0/authenticate HTTP/1.1
User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
Host: showcase.omh.io
Accept: */*
Content-Length: 73
Content-Type: application/x-www-form-urlencoded
user=user&password=password&requester=test&expires=1352375133000
Example HTTP response header:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Expires: Fri, 5 May 1995 12:00:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
Content-Type: application/json
Content-Length: 95
Date: Thu, 08 Nov 2012 23:35:13 GMT
Example HTTP response content:
{
"auth_token":"8fba448c-46c9-428d-a255-2d7cf2b71e45",
"expires":"2012-11-09T15:35:13.516-08:00"
}
Provides a way for users to read data. The data must be ordered based on some timestamp for each point. This needs to be consistent between requests. Returning the timestamp for a point is optional, so it can be completely arbitrary and not returned as long as it is consistent between requests.
The URI is omh/v0.1/read
The only allowed HTTP method is GET.
| Name | Description | Required |
|---|---|---|
| auth_token | An authentication token returned from the authenticate call above. | yes |
| requester | The username of the requester making this call. | yes |
| payload_id | The payload ID that represents the desired stream of data. | yes |
| payload_version | The version of the payload that represents the desired stream of data. | yes |
| owner | The username of the user about whom data is desired. This may or may not be the requesting user. | no |
| t_start | A W3C ISO8601-formatted date-time string. The earliest time for the resulting data. | no |
| t_end | A W3C ISO8601-formatted date-time string. The latest time for the resulting data. | no |
| summarize | A boolean that indicates whether or not to summarize the data. If the registry indicated that this data stream was not summarizable, a server has the option to return the data without any modifications or to return a HTTP 400 status code. | no |
| column_list | A column-separated list of columns to return. Each column is defined as ":::...". For example, given a record with two top-level fields, "T1" and "T2", where the first field, "T1", is an object with two sub-fields, "S1" and "S2", then supplying the following column list value, "T1:S2,T2", would return both top-level fields, but the only sub-field in “T1” would be “S2”. For the same scenario, supplying the column list value “S2,T2” would result in only “T2” being returned. This is because there is no top-level field “S2”, so that portion would be ignored, and “T1” is not requested, so it would not be returned. | no |
| num_to_skip | A number of data points to skip. The default is zero. | no |
| num_to_return | Overrides the default page size. If it is greater than the default, the request may be rejected or the server may limit the number of entries to the default. | no |
The response is a JSON object with the following fields.
| Key | JSON type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| metadata | object | This is metadata about the response. It contains the following fields
|
|||||||||||||||||||||
| data | An array of objects. | Each JSON object is a data point and must have the following fields.
|
|||||||||||||||||||||
Example HTTP request header
GET /app/omh/v0.1/read?auth_token=8fba448c-46c9-428d-a255-2d7cf2b71e45
&requester=test&payload_id=omh:ohmage:observer:edu.ucla.cens.Mobility:extended
&payload_version=2012050700&num_to_skip=1&num_to_return=1 HTTP/1.1
User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
Host: showcase.omh.io
Accept: */*
Example HTTP response header
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Set-Cookie: auth_token=8fba448c-46c9-428d-a255-2d7cf2b71e45; Expires=Sat, 10-Nov-2012 01:30:21 GMT; Path=/app; HttpOnly
Expires: Fri, 5 May 1995 12:00:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
Content-Type: application/json
Transfer-Encoding: chunked
Date: Fri, 09 Nov 2012 01:30:19 GMT
Example HTTP response content
{
"result":"success",
"metadata":{
"count":1,
"previous":"https://showcase.omh.io/app/omh/v0.1/read?auth_token=8fba448c-46c9-428d-a255-2d7cf2b71e45
&requester=test
&payload_id=omh%3Aohmage%3Aobserver%3Aedu.ucla.cens.Mobility%3Aextended
&payload_version=2012050700
&num_to_skip=0
&num_to_return=1",
"next":"https://showcase.omh.io/app/omh/v0.1/read?auth_token=8fba448c-46c9-428d-a255-2d7cf2b71e45
&requester=test
&payload_id=omh%3Aohmage%3Aobserver%3Aedu.ucla.cens.Mobility%3Aextended
&payload_version=2012050700
&num_to_skip=2
&num_to_return=1"
},
"data":[
{
"metadata":{
"id":"b2882e40-05fb-4f95-88bf-72902f72a29a",
"timestamp":"2012-11-08T17:13:00.195-08:00",
"location":{
"time":1352423580195,
"timezone":"America/Los_Angeles",
"latitude":34.0693758,
"longitude":-118.4430582,
"accuracy":20.0,
"provider":"WiFiGPSLocation:Network"
}
},
"data":{
"wifi_data":{
"scan":[
{
"ssid":"00:17:5a:b7:ef:90",
"strength":-56
},
{
"ssid":"00:1a:1e:1f:3a:24",
"strength":-82
},
{
"ssid":"00:1a:1e:1f:3c:d4",
"strength":-77
}
],
"time":1352423550836,
"timezone":"America/Los_Angeles"
},
"speed":0,
"accel_data":[
{
"z":-8.507708549499512,
"y":-0.49756529927253723,
"x":-4.559518337249756
},
{
"z":-8.392746925354004,
"y":-0.42092469334602356,
"x":-4.559518337249756
},
{
"z":-8.354427337646484,
"y":-0.5742059350013733,
"x":-4.559518337249756
},
{
"z":-8.277786254882812,
"y":-0.5358856320381165,
"x":-4.521198272705078
}
],
"mode":"still"
}
}
]
}