Skip to content

DSU Overview

Joshua Selsky edited this page Sep 30, 2013 · 17 revisions

Table of Contents


Introduction

The Open mHealth DSU (Data Storage Unit) API Specification is an open specification for unified information sharing across disparate data streams. The idea is simple: create an easy-to-understand set of APIs that allow siloed data stores to share information. Third-party applications that understand this API specification can then create a single set of tools to access data across any of the servers.

There are three fundamental components to data sharing. First, data stores must be able to define the data they share; this gives third-party clients a way to get uniform definitions of data, I.e., a given server’s data model. Second, third-party applications need a way for authenticated users to authorize their access. Finally, servers must have a simple, yet powerful API for reading the data.


Terminology

Data stores are any web-accessible application that stores data associated with a user. These are called Data Storage Units, or DSUs. Anyone that reads data from a DSU, which may itself be a DSU, is called a third-party application.

Data should be divided into "payloads". A payload is a set of data that conforms to a set of definitions. Each definition has its own ID and numeric version, and the definition with the greatest version is considered the "current version". This allows definitions to be modified to collect more or less data while maintaining the original data associated with the the previous version(s) of the payload. A DSU is required to implement an API call to read data payloads.

The "registry" is the set of known payload definitions and the definition's schema ID and versions. The registry is an open set of definitions; therefore, APIs that reference it do not require authentication. The registry definitions are defined by Concordia, a simple JSON schema language that focuses on strongly-typed definitions.

When implementing a DSU, the following API calls are required: authentication, registry, and read. There is an optional write call. If write is not implemented in a particular DSU, an HTTP 405 must be returned.


External Projects

To get started, there are a few external projects upon which this specification relies.

The first is OAuth 2.0. This is used to grant third-party applications access to a user’s data. The beta specification (see below) introduced the OAuth 2 requirement. The alpha specification required OAuth 1.0. In our earliest implementation we rolled our own authentication.

The next is Concordia. Concordia is a JSON schema language that defines strongly-typed JSON. JSON, like JavaScript, has weak typing for its variables which can allow for disparate types to be assigned to the same variable; this can make interpreting data very difficult. By requiring that the type of a field’s value or array entry must be the same between all data points, it gives consumers, especially automated ones, a reliable way to interpret the data. Concordia is extensible and allows developers flexibility. In the Open mHealth ecosystem, Concordia schemas are assigned schema IDs and versions. For a given schema ID-version pair, each data point must adhere to the Concordia schema, but additional fields can be added depending on system preference. This allows system-level specifics on data without sacrificing interoperability on the "core" data.

DSUs also rely on JSONPath and the W3C ISO 8601 date-time format.

All data returned from DSUs must be UTF-8 encoded.


API Rules

Requests

All API calls begin with omh/[version]/. The root of the API may be at any level of the web server's path hierarchy. For example, all of these are valid base addresses for a web server's Open mHealth APIs:

This prevents the Open mHealth APIs from hijacking the root of the domain.

Versioning

The APIs are all versioned to allow a single web server to handle multiple clients which each speak a different version of the API. This is appended to the root of the API’s domain. From the examples above, the version 1.0 of the API may look like:

Any minor release (1.1) under the major release (1) is required to be backwards compatible. The version used in the URLs will not change until a major version release.

Responses

The Open mHealth protocol relies on HTTP whenever possible and appropriate. For this reason, we use the HTTP response codes to indicate the success or failure of a request. The most commonly used codes are 200 (success), 4xx (the request is invalid), and 500 (the server failed).

The content of a response, if any, must be JSON, and the content type must be application/json. For successful requests, the response is defined for each API call. For unsuccessful requests, the HTTP specification should be consulted as to whether or not content is allowed, and, if so and desired, the content should be JSON.


Specification Versions

  • 1.0 - A further refinement of the alpha release based on working group and community input. This is the official 1.0 specification.
  • 1.0 Alpha - A refinement of the original API. If you are working on a project for the Heritage Challenge, use this version.
  • 0.1 - The initial API set as implemented for the Open mHealth Showcase at the 2012 mHealth Summit in Washington, DC.

⇡ top

You can’t perform that action at this time.