The API is implemented in a "RESTful" way where most of the interactions are done via entities. There are some extensions to the entities since we have ways of interacting with the entities.

All endpoints are protected by authentication to make sure that unauthorized parties do not access data they should not access.

The MDSi-Connect API offers only a single way of integrating with it - API keys per ICU using public-key cryptography. Each ICU can have multiple pairs of currently valid public/private keys. The API keys are separately issued for DEV and PROD environments and can not be used interchangably.

We want to make sure that the private key can not be hijacked in-traffic. The public-key method that we use to prevent this is HMAC. In short, HMAC calculates a signature of the request including the following components using the private key:

• string http_verb, // GET/POST/PUT
• string request_path, // /v1/action
• string content_sha256_hash, // JSON body stringified and sha256 hashed
• int timestamp, // unix timestamp in seconds

The signature is then included in the request headers and sent to the MDSi-Connect server. The signature of the request will also be calculated on the MDSi-Connect server. The two signatures are then compared to see whether the request is valid and whether it should be processed.

PS. Some endpoints return a URL that the end user should be redirected to. After redirecting, a time-limited session is created for the user so that they can use the system. For example, view or update a previously existing form.

In the rare case of GET requests, replace the json_encoded body with an empty string ("") and use the hash SHA256 hash of it. You might need to refactor the examples below to allow an empty request body.

PHP

The way that you should implement signature calculation in PHP is as follows.

function getHmacSignature(
    string $http_verb, // GET/POST/PUT
    string $request_path, // /v1/action
    array $body, // JSON request body
    int $timestamp, // unix timestamp in seconds
    string $api_secret // api secret as string
) {
    $content_sha256_hash = hash("sha256", json_encode($body));
    $string_to_sign = $http_verb . "\n" . $request_path . "\n" . $content_sha256_hash . "\n" . $timestamp;

    return hash_hmac("sha256", $string_to_sign, $api_secret);
}

JavaScript

For JavaScript (the example below is TypeScript, but you can remove the types), the signature calculation is as follows.

import { createHash, createHmac } from "node:crypto";

const sha256 = (content: string) => {
    return createHash("sha256").update(content).digest("hex");
};

const getHmacSignature = (
    http_verb: string, // GET/POST/PUT
    request_path: string, // /v1/action
    body: object, // JSON request body
    timestamp: number, // unix timestamp in seconds
    api_secret: string // api secret as string
) => {
    const content_sha256_hash = sha256(JSON.stringify(body));
    const string_to_sign = http_verb + "\n" + request_path + "\n" + content_sha256_hash + "\n" + timestamp;

    return createHmac("sha256", api_secret).update(string_to_sign).digest("hex");
};

Note: Only do this on the backend as otherwise the credentials are exposed!

To successfully authenticate, you need to provide the following headers with every request.

• The public API key to identify who is making the request
• The calculated request signature
• The timestamp that was used to calculate the signature

See below for descriptions of each required header.

PS. Some endpoints return a URL that the end user should be redirected to. After redirecting, a session is created for them so that they can use the system.

The API enables you to integrate with forms in various different ways. You can either integrate with a single form directly or you can integrate a whole "type of forms". In the "type of forms" option, the user will automatically also gain access to a per-patient or per-icu dashboard. The dashboards show all of the assigned forms and their status (filled, not filled) for each form.

Additionally, you can choose between different levels of patient identificators. They are described in more detail below.

The forms in MDSi-connect have various different types and can be requested to be filled at different points of time and sometimes even at different intervals.

For example, patient-based forms have the following types:

• ENTRY - when the patient enters the ICU
• VISIT - at any point of time during stay in the ICU
• PER_SHIFT - during each shift of staying in the ICU (usually 2-3 shifts)
• PER_DAY - during each day of staying in the ICU
• EXIT - when the parient exits the ICU

ICU-based forms have the following types:

• ICU - one-time forms to be filled in for the ICU
• ICU_PER_DAY - forms to be filled in once per day for the ICU

In most cases it makes sense to integrate using the dashboard option. You can hook the form dashboards into your processes and just provide the patient info and the type of form in the request. This means that you do not care how many and which (or if any) forms are assigned. You just call the same static endpoint.

If your workflows are very specific and you want the hospital staff to answer a certain form for each patient, you can also do that.

The patient identificator are used by the integrating PDMS to identify the individual patients throughout the whole life-cycle. Initially, when creating form submission requests. And also when asking for the form status for each patient.

The fields do not include any direct personal values of patients, but enough to be able to later connect the patient entries with their respective MDSi exports.

Soft connect

The so-called soft connect patient identificator includes the following fields:

• Age of the patient at the time of admission
• Admission date of patient into the ICU (Format: YYYYMMDDHHmm. YYYY = year, MM = month, DD = day of the month, HH = hours, mm = minutes)
• Chromosomal gender of the patient

Internal ID

This is the recommended integration option.

The internal ID logic is an extension of soft connect with an additional unique internal ID from your system. You only need to provide the soft connect fields in the form filling request step.

You can then use your internal ID for status queries instead of providing all of the soft connect fields every time. The internal ID can be anything that can be serialized to a string - floats, integers, strings. Ideally, a string should be provided already.

The examples below include various languages and tech stacks to query the "/api/v1/api-key-test" endpoint. This is also the recommended way - first implementing the signature calculation logic and then the more specific actions.

Below is an example using PHP Guzzle and composer.

use GuzzleHttp\Client;
use GuzzleHttp\RequestOptions;

$client = new Client(
    array(
        "base_uri" => getenv("MDSI_CONNECT_BASE_URI")
    )
);

$api_key = "yourApiKey";
$api_secret = "yourApiSecret";
$current_timestamp = time();

$signature = getHmacSignature(
    "POST",
    "/api/v1/api-key-test/",
    ["key" => "value", "second" => []],
    $current_timestamp,
    $api_secret
);

$request = $client->post(
    "/api/v1/api-key-test/",
    array(
        "headers" => array(
            "X-API-Key" => $api_key,
            "X-API-Timestamp" => $current_timestamp,
            "X-Api-Signature" => $signature
        ),
        RequestOptions::JSON => array(
            "key" => "value",
            "second" => array()
        ),
    ),
);
$response = json_decode($request->getBody());

Below is an example using PHP and cURL.

$body = ["key" => "value", "second" => []];

$ch = curl_init();

$time = time();

$apiKey = "yourApiKey";
$apiSecret = "yourApiSecret";

$string_to_sign = "POST" . "\n" . "/api/v1/api-key-test/" . "\n" . hash("sha256", json_encode($body)) . "\n" . $time;
$sig = hash_hmac("sha256", $string_to_sign, $apiSecret);

$headers = [
    "X-API-Key: " . $apiKey,
    "X-API-Timestamp: " . $time,
    "X-Api-Signature: " . $sig,
    "Content-Type: application/json"
];

// set URL and other appropriate options
curl_setopt($ch, CURLOPT_URL, "https://api.mdsi-connect.savedata.ch/api/v1/api-key-test/");
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_VERBOSE, true);
// you might need to disable SSL verification depending on your environment
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));

$ce = curl_exec($ch);

curl_close($ch);

Below is an example using JS and axios.

const apiKey = "yourApiKey";
const apiSecret = "yourApiSecret";

const timestamp = getCurrentTimeStamp();
const signature = getHmacSignature(
    "POST",
    "/api/v1/api-key-test/",
    body,
    timestamp,
    apiSecret
);

const { data } = await axios.post(
    "https://api.mdsi-connect.savedata.ch/api/v1/api-key-test/",
    body,
    {
        headers: {
            "X-API-Key": apiKey,
            "X-API-Signature": signature,
            "X-API-Timestamp": timestamp,
        }
    }
);