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.
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.
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.
All data returned from DSUs must be UTF-8 encoded.
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.
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.
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.
- 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.