Zugriff auf CuraGo-Daten inkl. Caching-Protokoll für Third-Party Apps

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 OpenAPI-Dokumentation heranzuziehen:

text

https://docs.curasoft.dev/cura-go.de

Da sehr große Datenmengen entstehen können, wird hier explizit auf die Kommunikation mit dem Server inklusive Caching-Protokoll eingegangen.

Die Request-Abfolge sollte so sein:

GET /auth/v3/app (Authentifizierung)

POST /api/v3/device/create (Erstellen eines Device-Tokens. Einmalig bei der ersten Kommunikation)
POST /api/v3/app/create (Erstellen eines App-Tokens. Einmalig bei der ersten Kommunikation)
    
POST /api/v3/app/login (App- und Device-Token als aktiv melden)

GET /api/v3/data/status (Neuerungen abfragen)
GET /api/v3/rest/{model} (Datensätze herunterladen)
POST /api/v3/rest/{model}/ack (Speichern der Datensätze bestätigen)
POST /api/v3/rest/{model}/cleanup (Löschen von veralteten Datensätzem bestätigen)

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 / Leistungserbringer zur Verfügung gestellt.

Diese beiden Keys werden beim Authentifizieren im Header mitgeschickt.

Nachdem man sich erfolgreich authentifiziert hat, erhält man ein Bearer-Token, welches bei allen weiteren Requests im Auth-Header mitgeschickt werden muss.
Das Bearer-Token ist ein JWT (JSON Web Token).

Wichtig in diesem JWT ist der Claim edk (encrypted DataKey).
Das ist der Datenschlüssel zum Entschlüsseln sensibler Daten. Dieser DataKey ist zusätzlich mit dem ACCESS-Key verschlüsselt.

Request

Route

http

GET /auth/v3/app

Header

text

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

Response

text

<bearer>

3. Device und App registrieren

Damit der Server ein effizientes Daten-Caching betreiben kann, gibt es das sogenannte Device-Token und App-Token.

Mit diesen Tokens kann der Server eindeutig erkennen, welche Datensätze beim Client gelöscht, geändert oder neu angelegt werden müssen.

Diese Tokens müssen nur einmalig registriert werden.

Im Body wird ein JSON-Objekt mit Informationen über die Client-Anwendung mitgeschickt.

Request für Device-Token

Route

http

POST /api/v3/device/create

Header

text

Authorization: Bearer <bearer>

Body

json

{
  "caption": "Linux Server Node A",
  "version": "1.0.0"
}

Response

text

<device_token>

Request für App-Token

Route

http

POST /api/v3/app/create

Header

text

Authorization: Bearer <bearer>

Body

json

{
  "device_token": "<device_token>",
  "app_info": {
    "name": "My fancy 3rd Party App",
    "version": "13",
    "build": "69"
  }
}

Response

text

<app_token>

4. App als aktiv melden

Das erzeugte app_token und device_token muss regelmäßig beim Server als aktiv gemeldet werden. Ansonsten werden alle Informationen zum Client irgendwann vom Server gelöscht (Aufräumarbeiten).

Route

http

POST /api/v3/app/login

Header

text

Authorization: Bearer <bearer>

Body

json

{
  "device_token": "<device_token>",
  "app_token": "<app_token>"
}

Response

json

{
  "server_time": "2021-10-15T11:00:00+02:00"
}

5. Abfragen von Daten

Das Abfragen von Daten erfolgt immer in drei Schritten:

Den Server nach Neuerungen fragen
GET /api/v3/data/status
Daten herunterladen
GET /api/v3/rest/{model}
Daten bestätigen
POST /api/v3/rest/{model}/ack
POST /api/v3/rest/{model}/cleanup

5.1 Den Server nach Neuerungen fragen

Das App-Token und die jeweiligen Ressourcen, die abgefragt werden sollen, werden hier im JSON-Objekt mit übergeben.

Request

Route

http

POST /api/v3/data/status

Header

text

Authorization: Bearer <bearer>

Body

json

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

Response

Body

json

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

Bedeutung der Response-Felder

Feld	Beschreibung
`cleanup_ids`	Alle IDs, die veraltet sind und beim Client gelöscht werden können. Aufeinanderfolgende IDs werden mit `..` abgekürzt.
`count_download`	Anzahl der Datensätze, die neu sind oder sich geändert haben (für evtl. Progress-Anzeigen).

5.2 Daten herunterladen

Beim Herunterladen der eigentlichen Daten ist es zwingend notwendig, dass alle IDs aus den Datensätzen, die vom Server ausgeliefert werden, lokal beim Client gespeichert werden.

Nur so kann eine fehlerfreie Kommunikation mit dem Server erreicht werden.

Request

Route

http

GET /api/v3/rest/{model}

Header

text

Authorization: Bearer <bearer>

Pfad-Parameter

text

{model}: z. B. Patient oder Mitarbeiter

Query-Parameter

text

token: <app_token>

Response

Body

json

[
  { "..": ".." },
  { "..": ".." }
]

Der Server liefert maximal 2000 Datensätze auf einmal aus.

Nachdem diese Datensätze bestätigt wurden, kann die nächste Abfrage erfolgen.
Das passiert so oft, bis der Server keine Datensätze mehr ausliefert.

5.3 Daten bestätigen

Nachdem Datensätze heruntergeladen und gespeichert wurden, muss dies beim Server bestätigt werden.
Dadurch wird der Datensatz bis zur nächsten Änderung nicht erneut ausgeliefert.

Hier gibt es zwei Requests:

Bestätigen neuer bzw. geänderter Daten
Bestätigen von Daten, die lokal gelöscht wurden

Request: Neuerungen und Änderungen bestätigen

Route

http

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

Header

text

Authorization: Bearer <bearer>

Pfad-Parameter

text

{model}: z. B. Patient oder Mitarbeiter

Body

json

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

Request: Löschen bestätigen

Nachdem die cleanup_ids beim Client gelöscht wurden, muss auch dies beim Server bestätigt werden:

Route

http

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

Header

text

Authorization: Bearer <bearer>

Pfad-Parameter

text

{model}: z. B. Patient oder Mitarbeiter

Body

json

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

6. Entschlüsseln von Daten

Sensible Daten liegen nur im verschlüsselten Format vor.

Dazu gehören zum Beispiel:

Patienten- und Mitarbeiternamen
Texte, Bilder und Sprachnachrichten der Übergabebucheinträge

Diese Daten sind mit dem sogenannten DataKey verschlüsselt.

Den Datakey erhält man unter dieser Route:

Route

http

GET /api/v3/client/access

Header

text

Authorization: Bearer <bearer>

Im JSON Response gibt es das Feld "datakey". Dieser Wert ist zusätzlich mit dem ACCESS-KEY verschlüsselt und muss vor der Nutzung entschlüsselt werden.

Alle Daten sind mit dem Verschlüsselungsverfahren AES-256 verschlüsselt. CuraSoft stellt Codebeispiele zum Entschlüsseln der Daten zur Verfügung (siehe Kapitel "Entschlüsseln von Daten" ).

Zugriff auf CuraGo-Daten inkl. Caching-Protokoll für Third-Party Apps ​

1. Allgemeines ​

2. Authentifizierung ​

Request ​

Response ​

3. Device und App registrieren ​

Request für Device-Token ​

Response ​

Request für App-Token ​

Response ​

4. App als aktiv melden ​

Response ​

5. Abfragen von Daten ​

5.1 Den Server nach Neuerungen fragen ​

Request ​

Response ​

Bedeutung der Response-Felder ​

5.2 Daten herunterladen ​

Request ​

Response ​

5.3 Daten bestätigen ​

Request: Neuerungen und Änderungen bestätigen ​

Request: Löschen bestätigen ​

6. Entschlüsseln von Daten ​

Zugriff auf CuraGo-Daten inkl. Caching-Protokoll für Third-Party Apps

1. Allgemeines

2. Authentifizierung

Request

Response

3. Device und App registrieren

Request für Device-Token

Response

Request für App-Token

Response

4. App als aktiv melden

Response

5. Abfragen von Daten

5.1 Den Server nach Neuerungen fragen

Request

Response

Bedeutung der Response-Felder

5.2 Daten herunterladen

Request

Response

5.3 Daten bestätigen

Request: Neuerungen und Änderungen bestätigen

Request: Löschen bestätigen

6. Entschlüsseln von Daten