Getting started : App

What is it?

A MIDATA app may be a mobile application, a website or a desktop application that uses the API of the MIDATA platform.

How do I start?

MIDATA runs multiple instances of the MIDATA platform for different purposes. At test.midata.coop you find the development and testing instance.

  • Submit your request for a developer account on the test platform. Please note that the issuing of a developer account is conditioned to the pre-existence of a contract and/or a partnership agreement between MIDATA and the requesting party.
  • Then register your application on the test platform.
  • To have access to some data configure the access filter for your app.
  • In the API debugger you can test all your queries and ideas before you implement them.
  • Choose a development environment and supporting libraries and implement your application.
  • Your application should use OAUTH2 for authentication.
  • Look at statistics to improve your application and track errors.
  • Link your app with required research projects or other service backends.
  • If everything runs fine contact MIDATA to copy your application definition to a productive system.

What libraries should I use?

For developing an external application you may use any technology you like. Consider using a FHIR library to communicate with the server.

MIDATA has support for multiple FHIR versions. We strongly recommend the newest available version. Please read about FHIR version support.

Please include the FHIR version to be used into your request headers as described.

Authentication

The platform supports SMART on FHIR authentication using the public standalone launch sequence. SMART on FHIR authentication is based on OAUTH2. MIDATA offers the OpenId connect userinfo endpoint.

Here is a link to the official specification that may help you during development:

SMART on FHIR app launch

Retrieving the FHIR metadata statement

Your application should first query for the authorization endpoints to use. Query for the FHIR metadata statement

GET https://test.midata.coop/fhir/metadata

The response will include the required information:

{
  "resourceType": "CapabilityStatement",
  "status": "active",
  ...
  "rest": [
    {
      "mode": "server",
      "security": {
        "extension": [
          {
            "url": "http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris",
            "extension": [
              {
                "url": "token",
                "valueUri": "https://test.midata.coop/v1/token"
              },
              {
                "url": "authorize",
                "valueUri": "https://test.midata.coop/authservice"
              }
            ]
          }
        ]
      },
      ...

Retrieving a login code

With OAuth2 the authentication is done in two steps:

First your application needs to open a browser window with the OAuth login page of MIDATA. On this OAuth login page the user can

  • Log in
  • Create a new account
  • Confirm to consents / Participation to research

After the user is done the control is given back to your application with a code token.

The URL that your application must open in the browser looks like this:

GET https://test.midata.coop/authservice
    ?response_type=code
    &client_id=myappname
    &redirect_uri=https:%2F%2Flocalhost%2F%23%2F
    &device_id=debug

The device_id parameter is optional. If it is used it should contain any string with at least 4 characters length that identifies the device of the user. It may be just a random string that is generated on the device and stored. It MUST stay the same on one device and SHOULD be different for different devices.

Exchanging the code for a token

In the second step your application can exchange the code token for a session token and a refresh token. The session token can be used to communicate with the server.

The request will look like this:

POST https://test.midata.coop/v1/token 
    ?grant_type=authorization_code
    &redirect_uri=https:%2F%2Flocalhost%2F%23%2F
    &client_id=myappname
    &code=j5u6DtQmj1bejdWLoYSSkJQeiT6kPdtYj9yRzlkX28HS
Content-Type: application/x-www-form-urlencoded

A successful response looks like this:

{
  "state":"none",
  "access_token":"oSkJQeiTxx4iiK...hqKhFp2Jj5u6DtQmj1bejdWLoYSX2kNq",
  "token_type":"Bearer",
  "scope":"user/*.*",
  "expires_in":21600,
  "patient":"56ded6c179c7212042b29984",
  "refresh_token":"SZ7WF5diFgp...EKhNguO5do8faZG26kPdtYj9yRzlkX28HSrMfXftl"
}

The session token is valid for a maximum time of 8 hours.

The refresh token may be used to receive a new pair of session token and refresh token.

Please note that each refresh token is only valid once.

So your application needs to store the new refresh token in a database, file system or local storage.

Retrieving OpenId connect userinfo

If the app needs information about the logged in user it may call the openId connect userinfo endpoint at:

GET https://test.midata.coop/v1/userinfo
Authentication: Bearer <access_token>

The userinfo endpoint may be called with GET or POST request method. The response looks like:

{
  "sub": "5703c42faed645223ffbb9dc",
  "name": "Hugo Beispiel",
  "family_name": "Beispiel",
  "given_name": "Hugo",
  "email": "hugo.beispiel@example.com",
  "email_verified": true,
  "gender": "male"
}