https://github.com/openmhealth/developer/wiki/DSU-Overview 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 payloads and the payloads’ versions and definitions. 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.
The "catalog" is a registry for a given user. The catalog exists for the case where a given user may have more than one stream of data from the same device or app.
When implementing a DSU, the following API calls are required: authentication, registry, and read. The following API calls are optional: catalog and write. For the optional API calls, the DSU must return the HTTP 405 response code if the calls are not implemented.
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.
DSUs also rely on JSONPath and the W3C ISO 8601 date-time format.
All data returned from DSUs must be UTF-8 encoded.