API Documentation for docbox.swiss

This page forms the central documentation index for all docbox apis

Naming & URL Scheme

We provide different, mostly product- oder use-case-based APIs in different versions. Therefore, the following global naming and versioning schema is used:

api[.ENVIRONMENT].docbox.swiss/[API]/[VERSION]/path

The environment part of the host identifies the used environment.
Example for the test environment: api.test.docbox.swiss.
The first URL segment identifies the API.
Example for the hospital API in test: api.test.docbox.swiss/hospital.
The second URL segment identifies the version.
Example for version 1 of the hospital API in test: api.test.docbox.swiss/hospital/v1.

See the following sections to learn how to build your desired urls...

Environments

The docbox application, it services and apis run in different environments, which are logically seperated from each other. This environments are identified by their (sub)domains. The production environment runs on the root domain (*.docbox.swiss). Other environments run at *.[ENV].docbox.swiss (e.g. *.test.docbox.swiss).

The following table serves as an endpoint URL reference:

System	Test Environment	Production Environment
Identity Provider	auth.test.docbox.swiss	auth.docbox.swiss
API	api.test.docbox.swiss	api.docbox.swiss

APIs

APIs are identified by the very first URL segment after the host. They are defined by topic and/or product and used to group endpoints and systems. Some APIs will require specific roles or even be blocked for some clients. Every API has its own OpenAPI specification and therefore an own API documentation.

Authentication

The APIs exposed use OpenID Connect a.k.a. "OIDC" (an extension of OAuth2) authentication. You should have received Client Credentials for test and production environment, which you can use to get authorization tokens. You can use one of the following mechanisms to authenticate:

** Authorization Code Flow **
** Implicit Flow **
** Device Code Flow **

Authorization Code Flow

Heads Up: This is just a simple example of how the OIDC authorization code flow (which is highly standartized) works. You should not do it by hand or implement it yourself. Probably, almost every programming language / framework provides a library for OIDC authorization.

1. Request authorization code

Redirect the user (in a browser) to the following URL: https://auth.test.docbox.swiss/realms/docbox/protocol/openid-connect/auth?response_type=code&client_id={{your_client_id}}&redirect_uri=http://localhost&state=fj8o3n7bdy1op5

2. Extract authorization code

On the provided redirect uri, here http://localhost, the following request will be received:

http://localhost/?state=fj8o3n7bdy1op5&session_state=9d9978aa-9014-42b7-a5ec-1dbdce347eae&code=b63b6a9d-d689-4a1c-8922-53700914ea4e.9d9978aa-9014-42b7-a5ec-1dbdce347eae.f3765404-d234-4cc0-8521-b4364684b49c

You'll need to extract the two parameters session_state and code for later use...

3. Obtain access token using authorization code

The access token needs to be obtained directly aufter the authorization code redirect, because the code has, for security reasons, a very short expiration time (seconds).

The following curl request describes how to obtain the access & refresh token:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&session_state=9d9978aa-9014-42b7-a5ec-1dbdce347eae&code=b63b6a9d-d689-4a1c-8922-53700914ea4e.9d9978aa-9014-42b7-a5ec-1dbdce347eae.f3765404-d234-4cc0-8521-b4364684b49c&redirect_uri=http://localhost&client_id={{your_client_id}}&client_secret={{your_client_secret}}" \
  https://auth.test.docbox.swiss/realms/docbox/protocol/openid-connect/token

The response, if successful, will be something similar to:

{
  "access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJr ... 8iCqsPgrTf1IqKA2A_dcHEflnJLPVmZaGB4AMnSNEvQ",
  "expires_in":900,
  "refresh_expires_in":86400,
  "refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIg ... BR-1XIr-M1Fo",
  "token_type":"Bearer",
  "not-before-policy":0,
  "session_state":"603df6a0-ae46-40b9-b143-1073cf721b9d",
  "scope":"profile email"
}

access_token

This token needs to be submitted in the Authorization HTTP header, to make APi calls.

expires_in

Defines the timespan, how long the access_token is valid.

refresh_token

This token is used to obtain a new access token, together with the3 client secret, if the access_token expires.

refresh_expires_in

Indicates the timespan in which the refresh_token is valid. It's by default 24h - (session time), so if the user is logged-in already for 30 minutes, it will be 23h 30m.

token_type

Defines the type of the token, which needs to be prefixed in the Authorization HTTP header.

Format:

Authorization: {token_type} {access_token}

Example:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJr ... 8iCqsPgrTf1IqKA2A_dcHEflnJLPVmZaGB4AMnSNEvQ

session_state Security measure: Compare the session state value with the one you got with the first (authorization code) redirect. Only use the token, if the session-state of both responses is the same.

scope

Defines the scopes, the token is authorized fo use.

4. Obtain access token using refresh token

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCIg ... BR-1XIr-M1Fo&client_id={{your_client_id}}&client_secret={{your_client_secret}}" \
  https://auth.test.docbox.swiss/realms/docbox/protocol/openid-connect/token

The response, if successful, will be similar to authorization code flow and provide the following response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIzUTdOSVB0dHRZUzZCZ0xzeG9jMEJnZWVGaDFhV0JOYlJ4bEF5bEd0bXR3In0.eyJleHAiOjE2NDgxMTcxMTIsImlhdCI6MTY0ODExNTMxMiwiYXV0aF90aW1lIjoxNjQ4MTExNzMyLCJqdGkiOiI0Mjg2ZmI3MC04ZTZkLTQzMGEtYjVlZS1kMmEzMTc3M2IxZWQiLCJpc3MiOiJodHRwczovL2F1dGgudGVzdC5kb2Nib3guc3dpc3MvcmVhbG1zL2RvY2JveCIsImF1ZCI6ImFjY291bnQiLCJzdWIiOiIzNzExZmM4MC1jZmNmLTRhOWQtODA2OC05YTFjN2MyNjNjYWEiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJleHRfdml0b21lZCIsInNlc3Npb25fc3RhdGUiOiIwMWFiN2Q4ZC1iNmM5LTRmZTktYTE2Ny0xZjZkNjE5MGU4MzkiLCJhY3IiOiIwIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImRlZmF1bHQtcm9sZXMtZG9jYm94Iiwib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBlbWFpbCIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwicHJlZmVycmVkX3VzZXJuYW1lIjoidml0by10ZXN0LTEiLCJsb2NhbGUiOiJkZSJ9.eJhW7V770JgpYxHWoq2DxXUCP0pD_zA7ERvto3KZiWQEsOBeOX3JMzrTc5uNu_vHEDGEsVts_OqNJ-UA4gKxwfuqPsk8cFoBrZeBzNQ8SpH61tNCldIvpoteuR45rL-f7_n4Xe2Thh-Fhfyc1LbyiQiHXwSeeBOV5mK6AuX-_mlY6WFDj6aZ2ohFlqCCniyHsJ9udqsRRGlklXXACwPQRPrv7awTIO1i4Z8ipFTyWOqRYsY1ZW7mJPA8gQRzI4uXaAsA1kVmD8WlGtdNzfj66ZWwMuFkNPxyberGxoIGcddtaOuL5_osx4CAvHxj26bYbqlXdZ3SIxPap7FQRFwH5w",
  "expires_in": 1800,
  "refresh_expires_in": 82820,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI2YjhjOTAzYS0xMTExLTRmOTUtYWQ1Yi1iMTU4MjYzOTg0YjYifQ.eyJleHAiOjE2NDgxOTgxMzIsImlhdCI6MTY0ODExNTMxMiwianRpIjoiNTM3NDllNTctY2M1Ni00YmY3LWIyY2MtYzhmOWI5MzlkYTBmIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLnRlc3QuZG9jYm94LnN3aXNzL3JlYWxtcy9kb2Nib3giLCJhdWQiOiJodHRwczovL2F1dGgudGVzdC5kb2Nib3guc3dpc3MvcmVhbG1zL2RvY2JveCIsInN1YiI6IjM3MTFmYzgwLWNmY2YtNGE5ZC04MDY4LTlhMWM3YzI2M2NhYSIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJleHRfdml0b21lZCIsInNlc3Npb25fc3RhdGUiOiIwMWFiN2Q4ZC1iNmM5LTRmZTktYTE2Ny0xZjZkNjE5MGU4MzkiLCJzY29wZSI6InByb2ZpbGUgZW1haWwifQ.3kkTkFolvL9EuqeLTIKm5-3eooz95mH-whqyKN6Kw70",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "01ab7d8d-b6c9-4fe9-a167-1f6d6190e839",
  "scope": "profile email"
}

It contains a new access_token and a new refresh_token to use.

Hospital

A set of endpoints to interact with hospitals and other healthcare institutions

Hospital API Documentation

ABP

Not yet documented...

Old / Legacy APIs

There are also some legacy APIs used in some scenarios. Those endpoints should not be used for new implementations and carry their own documentation. Legacy APIs will not be documented here.

Versions

The version URL segment contains the API version as one single number, prefixed by a small 'v'.

APIs are versioned independently of each other. An increment of an API version always indicates, that non reverse-compatible changes were introduced with it. Changes which are reverse-compatible will be rolled out on the same API version. Older API versions will be flagged as deprecated, and after notifaction of the consuming parties and 1 year grace period, be deactivated.

Errors

Errors (also validation and client) are always returned as appropriate HTTP codes in combination with application/problem+json objects. The following JSON snippet shows an example response:

{
  "type": "https://api.docbox.swiss/problem/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Object with id 08-15 does not exist"
}

See RFC-7807 for details.