Zugriff auf die cura.go API mit Caching-Protokol

1. Allgemeines

In der folgenden Kurzanleitung wird grob skizziert, wie eine Third-Party App mit dem CuraGo Server kommunizieren sollte. Für detailliertere Angaben ist die Open-API-Dokumentation (https://docs.curasoft.dev/cura-go.de) heranzuziehen. Da sehr große Datenmengen entstehen können, wird hier explizit auf die Kommunikation mit dem Server inkl. Caching Protokoll eingegangen.

2. Authentifizierung

Die Authentifizierung besteht aus zwei Informationen:

• API-Key: Erlaubt den Serverzugriff.
• ACCESS-Key: Erlaubt den Datenzugriff.

Der API-Key wird von CuraSoft zur Verfügung gestellt. Der ACCESS-Key wird vom Kunden/Pflegedienst/Leistungserbringen zur Verfügung gestellt.

Diese beiden Keys werden beim Authentifizieren im Header mitgeschickt. Nachdem man sich erfolgreich authentifiziert hat, bekommt man ein Bearer-Token, welches man bei allen weiteren Requests im Auth-Header mitschicken muss. Das Bearer-Token ist ein JWT (JSON Web Token). Wichtig in diesem JWT ist der Claim "adk" (AppDataKey). Das ist der Datenschlüssel zum Entschlüsseln von sensiblen Daten. Dieser AppDataKey ist zusätzlich mit dem ACCESS-Key verschlüsselt.

Request

Route:
    GET /auth/v3/app

Header:
	X-API-KEY: <api_key>
	X-ACCESS-KEY: <access_key>

Response

<bearer>

3. Device registrieren

Damit der Server ein effizientes Daten-Caching betreiben kann, gibt es das sogenannte Device-Token. Mit diesem Device-Token kann der Server eindeutig erkennen welche Datensätze beim Client gelöscht, geändert oder neu angelegt werden müssen. Das Device muss nur einmalig registriert werden. Im Body wird ein JSON Objekt mitgeschickt, welches Informationen über die Client-Anwendung enthält.

Request

Route:
    POST /api/v3/device/create

Header:
	Authorization: Bearer <bearer>

Body:
{
	"caption": "Fancy 3rd Party App",
	"version": "1.0.0"
}

Response

<device_token>

4. Abfragen von Daten

Das Abfragen von Daten erfolgt immer in drei Schritten.

1. Den Server nach Neuerungen fragen:

    /api/v3/data/status
   

2. Daten herunterladen:

    /api/v3/rest/{model}
   

3. Daten bestätigen:

    /api/v3/rest/{model}/ack
    /api/v3/rest/{model}/cleanup
   

4.1 Den Server nach Neuerungen fragen

Das Device-Token vom Client und die jeweiligen Ressourcen, die man Abfragen will, werden hier im JSON Objekt mit übergeben.

Request

Route:
    POST /api/v3/data/status

Header:
	Authorization: Bearer <bearer>

Body:
{
	"jobs": [
		{
			"token": "<device_token>",
			"models": [
				"Patient",
				"Mitarbeiter"
			]
		}
	]
}

Response

Body:
	[
		{
			"model": "Patient",
			"cleanup_ids": "1,4..10,12",
			"count_download": 4
		},
		{
			"model": "Mitarbeiter",
			"cleanup_ids": "",
			"count_download": 100
		}
	]

Im Response werden die Neuerungen für die jeweiligen Modelle geliefert. "cleanup_ids" sind alle IDs die veraltet sind und beim Client gelöscht werden können. Aufeinanderfolgende IDs werden mit ".." abgekürzt. "count_download" ist die Anzahl von Datensätzen, die entweder neu sind oder die sich geändert haben.

4.2 Daten herunterladen

Beim Herunterladen der eigentlichen Daten ist es zwingend notwendig, dass man alle IDs aus den Datensätzen, die vom Server ausgeliefert werden, auch lokal beim Client speichert. Nur so kann ein fehlerfreies Kommunizieren mit dem Server erreicht werden.

Request

Route:
   GET /api/v3/rest/{model}

Header:
	Authorization: Bearer <bearer>
	
Pfad-Parameter:
	{model}: z.B. Patient oder Mitarbeiter

Query-Parameter:
	token: <device_token>

Response

Body:
	[
		{..},{..}
	]

Der Server wird maximal 2000 Datensätze auf einmal ausliefern. Nachdem diese Datensätze bestätigt wurden, kann die nächste Abfrage erfolgen. Das passiert genau so oft, bis der Server keine Datensätze mehr ausliefert.

4.3 Daten bestätigen

Nachdem man Datensätze heruntergeladen und gespeichert hat, muss dies beim Server bestätigt werden. Somit wird dieser Datensatz bis zur nächsten Änderung nicht erneut ausgeliefert. Hier gibt es zwei Requests. Zum Einen das bestätigen der neuen/geänderten Daten und zum Anderen das bestätigen der Daten, die man lokal gelöscht hat.

Request (Neuerungen und Änderungen bestätigen)

Route:
   POST /api/v3/rest/{model}/ack

Header:
	Authorization: Bearer <bearer>
	
Pfad-Parameter:
	{model}: z.B. Patient oder Mitarbeiter

Body:
	{
		"token": "<device_token>",
		"ids": "1,4..10,12"
	}

Request (Löschen bestätigen)

Route:
   POST /api/v3/rest/{model}/cleanup

Header:
	Authorization: Bearer <bearer>
	
Pfad-Parameter:
	{model}: z.B. Patient oder Mitarbeiter

Body:
	{
		"token": "<device_token>",
		"ids": "1,4..10,12"
	}

5. Entschlüsseln von Daten

Sensible Daten liegen nur im verschlüsselten Format vor. Wie z.B. Patienten- und Mitarbeiternamen oder Texte, Bilder und Sprachnachrichten der Übergabebucheinträge. Diese Daten sind mit dem DataKey verschlüsselt. Den DataKey kann man sich aus dem "adk" Claim im JWT extrahieren. Dieser ist allerdings zusätzlich mit dem ACCESS-Key verschlüsselt. Alle Daten sind mit dem Verschlüsselungsverfahren AES-256 verschlüsselt. CuraSoft stellt Codebeispiele zum Entschlüsseln der Daten zur Verfügung.