Getting started : Project analyzer

What is it?

A project analyzer is an external application that connects to the MIDATA platform and accesses data of a research project.

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.
  • Register a researcher account and setup a project.
  • As researcher: Add your analyzer to the research project.
  • As researcher: Generate an API key so that your service may connect.
  • 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.
  • Look at statistics to improve your application and track errors.
  • If everything runs fine contact MIDATA to copy your application definition to a productive system.
  • Have researcher on productive system setup the research project.

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 / Manage service keys

A user with role researcher needs to connect the project analyzer with a project. As researcher go to the tab “Applications” of a project.

In the section “Aggregators, Analysis and Interpretation Applications” select the project analyzer and connect it to a group of the research project. Afterwards a new manage API keys section will be shown on the same page.

One the manage API key management section you have several options:

  • Click on “Add key” to generate a session key. The key will be displayed only once. You need to copy it into the application.
  • By clicking on “Revoke this key” you can invalidate a previously generated key. This key can no longer be used. By

When you generate a new key various types of keys are offered to you:

Static authentication token

This may be used directly as “Bearer” token in the “Authorization” header of each request. The lifetime of the token is one year or until it is revoked. If someone steals the token that person will also have access until you replace the token with a new one.

Refresh token

This token may be used as refresh token using the OAuth2 protokoll. The token is exchanged for a pair of authentication token and new refresh token. As soon as the refresh token is used it expires and only the newly issued refresh token is valid. The issued authentication tokens are only valid for 5 hours or until until the refresh token is used to obtain a new token pair. Using the refresh token mechanism will increase security of the system. As downside your service will need to store the currently valid refresh token in a database, file system or local storage.

Client Certificate

A client certificate may be used to authenticate each request. For using client certificates create a certificate request (CSR) using the CN (common name) shown in the dialog. Here is an example for creating a CSR using openssl:

openssl req -new -nodes -keyout client_certificate.key -out client_certificate.csr

Send the CSR via email to support@midata.coop and give the MIDATA instance domain you need the certificate for in the mail subject. We will send you back the client certificate as PEM file. The certificate will be valid for a maximum of one year. If you revoke the API key the certificate will immideately expire.

Never give away your client certificates private key! Please do not use the client certificate for anything other than authentication to MIDATA.