Skip to content
This repository has been archived by the owner on Apr 29, 2021. It is now read-only.

DSU 1.0 Specification

Jump to bottom
Joshua Selsky edited this page Apr 24, 2014 · 9 revisions

Table of Contents

Authentication

A DSU is free to implement its own form of user-facing authentication. Open mHealth does not prescribe authentication or access rules for a given DSU because each DSU may have its own access policy and user roles.

⇡ top

Authorization

Third-party authorization allows an authenticated user to authorize a third-party request for data.

The third-party authorization protocol that Open mHealth uses is OAuth 2.0. Please see the OAuth 2.0 Protocol specification for more information.

All OAuth APIs reside under the path omh/v1/auth/oauth.

⇡ top

Registry Read

Request

The registry provides the Concordia definitions for data payloads that are served up from a DSU. The only allowed HTTP method is GET.

The request URL has three paths.

  • The path to get all schema IDs from a DSU is: omh/v1.
    • This will return a JSON Array of strings that are Open mHealth schema IDs.
    • ["omh:example:steps", "omh:example:velocity", "omh:example:mets"]
  • The path to get all schema versions for a specific schema ID is: omh/v1/<schema_id>.
    • This will return a JSON Array of numbers that are schema versions for the provided schema ID.
    • [1,2]
  • The path to get a schema for a specific ID-version pair is: omh/v1/<schema_id>/<schema_version>.
    • This will return the Concordia schema (a JSON Object) that defines the data referenced by the schema ID-version pair.
    • The meta-data about the schema, if any, will be added as headers.
    • See below for an example.

Parameters

Name Description Required
num_to_skip Skips forward the number of registry entries. If this parameter is not provided, the default of zero is used. 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. If this parameter is not provided, the default value is the maximum page size, which is 100. No.

Response

This is the description of the results when both an ID and version are given.

This will always return exactly one result. When no result exists (e.g. the ID and/or version do not exist), a HTTP 404 status code will be returned.

The response is a JSON object that is the definition.

Example HTTP request header

 GET /app/omh/v1/omh:example:steps/1 HTTP/1.1

Example HTTP response header

 HTTP/1.1 200 OK
 Content-Type: application/json

Example HTTP response content

{
  "type":"object",
  "doc":"This is an example.",
  "fields":[
    {
      "name":"count",
      "type":"number",
      "doc":"A simple step count."
    }
  ]
}

⇡ top

Read

Provides a way to read data.

The path is /omh/v1/<schema_id>/<schema_version>/data. The only allowed HTTP method is GET.

Data returned by the Read API should be ordered based on some timestamp for each point and the ordering must be consistent between requests. Returning the timestamp for a point is optional, even if it is requested, so it can be completely arbitrary and not returned as long as the ordering is consistent between requests.

Request

Parameters

The auth_token must be included in the HTTP header section as a cookie.

Name Description Required
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.
column_list A comma-separated list of JSONPath expressions. Limits the results for each point. This includes the point’s metadata and data, so all expressions should begin with $.metadata or $.data No.
num_to_skip The number of results for skip before returning the first result. If not provided, 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.

Response

Headers

The count, next URL and previous URL are part of the HTTP headers. This is done in order to allow clients to perform an HTTP HEAD request to obtain the request metadata (E.g., a client may want to fast-forward through results without having to issue the full GET).

Key JSON type Description
Count number The number of points being returned.
Total-Count number The total number of visible elements in the list regardless of query parameters. This is only recommended, and systems that find it too arduous should attempt to give an estimate.
Previous string The URL for the previous set of data. This is based on the parameters, so, if data exists before this point but there are no points between the given t_start and the first point, then this field may be omitted. This field may be provided even if this response and/or this URL will return no data.
Next string The URL for the next set of data. This is based on the parameters, so, if data exists after this point but there are no points between the last point and t_end, then this field may be omitted. This field may be provided even if this response and/or this URL will return no data.
Example
 HTTP/1.1 200 OK
 Content-Type: application/json
 Count: 1000
 Previous: /omh/v1/omh:schema:id/1/data? ...
 Next: /omh/v1/omh:schema:id/1/data? ...

Body

The response is a JSON array of JSON objects where each object is a point with the following fields.

Key JSON type Description
metadata object This is metadata about this point. It may include any of the following fields.
Key JSON type Description
id string A unique ID for this data point.
timestamp string A W3C ISO8601-formatted date-time value.
source object An object containing information regarding the source of the data point. This object can contain an arbitrary number of fields and serves to identify provenance on the data.
This metadata section may include any other system-specific fields; however, they will be non-standard fields and their use must be explicitly defined for third-party applications.
data a JSON array or object The data point’s data. This must conform to the schema definition as provided by the registry for the schema ID-version pair that identifies this point.

Example HTTP request header

GET /omh/v1/omh:ohmage:observer:edu.ucla.cens.Mobility:extended/2012050700/data
   ?num_to_skip=1&num_to_return=1 HTTP/1.1
 Cookie: auth_token=8fba448c-46c9-428d-a255-2d7cf2b71e45;

Example HTTP response header

 HTTP/1.1 200 OK
 Content-Type: application/json
 Count: 1
 Previous: /omh/v1/omh:ohmage:observer:edu.ucla.cens.Mobility:extended/2012050700/data
   ?num_to_skip=0&num_to_return=1
 Next: /omh/v1/omh:ohmage:observer:edu.ucla.cens.Mobility:extended/2012050700/data
   ?num_to_skip=2&num_to_return=1

Example HTTP response content

   [
      {
         "metadata":{
            "id":"b2882e40-05fb-4f95-88bf-72902f72a29a",
            "timestamp":"2012-11-08T17:13:00.195-08:00"
         },
         "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"
         }
      }
   ]

⇡ top

Write

Request

Provides a way to write data. This call is optional. DSUs that do not support write must return an HTTP 501 response code.

The path is /omh/v1/<schema_id>/<schema_version>/data, and one must use a POST to write data.

Check the FAQ for why write is optional.

Parameters

Name Description Required
auth_token The uploading user's authentication token. Yes.
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. Yes.

Response

If the user is not authenticated, an HTTP 401 will be returned.

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.

Example HTTP request header

 POST /omh/v1/write HTTP/1.1
 Cookie: auth_token=8fba448c-46c9-428d-a255-2d7cf2b71e45;
 
 schema_id=omh:ohmage:observer:edu.ucla.cens.Mobility:extended
 &schema_version=2012050700
 &data=<JSON Array of points that adhere to the schema ID-version pair.>

Example HTTP response header

HTTP 204

⇡ top

Clone this wiki locally