Getting started : External Service
What is it?
An external service is an application that uses the API of the MIDATA platform.
The services accesses the shared data of all user accounts that use the service using one session. One person or a team must be assigned as manager of the service. That person or team may create and revoke session keys for the service.
A account holder may subscribe to using the service. Subscribing means to make data from his user account available to the service session.
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.
- Generate an API key so that your service may connect.(see below)
- 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.
- Management of API keys may be transfered to a healthcare provider account or a team.(see below)
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.
Service Management
After creation the developer of the service is automatically also the manager of the service. So the developer may create session keys for testing. When you request MIDATA to take the service to the production system please state who should be managing session tokens on the productive system.
Authentication / Manage service keys
On the overview page of your application click on the “Manage your API keys” link to in the “application type” row. If you have a different role open your user profile by clicking on your name in the top menu and select “Manage API keys” in the “more…” dropdown.
One the manage API key page 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 a 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.
Data Broker
There is a special variant of external service called “Data Broker” that enforces access restrictions for multi Organization use. A data broker is software running outside of the MIDATA platform. This type of software acts as middleware between Midata and multiple organizations using the middleware. In contrast to the external service the data broker has no direct access to all users that are using the service. Instead need to be consents between the account holders and the organizations using the service and between the organization and the data broker. With each request the data broker needs to provide the id of the organization on whose behalf the request is made.
Differences: Project Analyzer / Data Broker
| External Service | Data Broker |
|---|---|
| Account holders need to have consents directly with the external service | Account holders need to have consents with the organizations they want to share data with |
| The API-Key grants direct access to the account holders data | The API-Key only grants only access to public data |
| There are no additional parameters for API-Keys | In addition to the API-Key an organization id may be passed as parameter which grants access to data shared with the target organization. |
Data Broker - Authentication
When the data broker performs an API call in addition to the normal access token or client certificate the organization on whose behalf the request is made may be added to the Authentication. If the application uses an API-Key the organization id is added as parameter to the API-Key. Parameters are seperated using a semicolon from the API-Key. For example if the organization id is 12345 the Authorization header may look like this:
Authorization: Bearer 234kjhsdf2...2fgk32m; grp=12345
If a client certificate is used then the parameter must still be sent as Authorization header. In that case the token in the Authorization header is ignored. As the token may have any value the fixed value “client-certificate” may be used to make it clear that a client certificate is provided. For the organization with id 12345 the Authorization header with client certificate used may look like this:
Authorization: Bearer client-certificate; grp=12345