03. August 2017

synTechTalk: Einstieg in die comuny-API

synTechTalk: Einstieg in die comuny-API (Bild: whiteMocca/shutterstock.com)

comuny bietet eine zentrale Plattform, auf der Anbieter aus den verschiedensten Bereichen des Gesundheitswesens ihre Lösungen mit wenig Aufwand datenschutzkonform entwickeln und über eine definierte Schnittstelle „anschließen“ können. Durch die Mischung aus erfüllten Datenschutzauflagen, dem bereitgestellten Platz für eigene Apps und dem Zugang zu einer Community für den Wissensaustausch stellt comuny für Entwickler eine Plattform voller Vorteile dar. Teil eins dieses synTechTalk-„Zweiteilers“ beschäftigt sich mit der angesprochenen Schnittstelle (API) und zeigt, wie sie benutzt werden kann, um Daten abzulegen.

Die comuny-Schnittstelle ist eine gewöhnliche REST-API. Die Anfragen und Antworten sind in JSON gehalten. Die Authentifizierung erfolgt via OAuth2. Alle weiteren Informationen können in der API-Dokumentation (siehe ZIP-Datei im nachfolgenden Abschnitt) nachgelesen werden.

Voraussetzungen

Um comuny nutzen zu können, wird ein Konto benötigt. Dieses lässt sich hier in wenigen Schritten erstellen. Im Anschluss muss die „comuny CRUD“-Applikation freigeschaltet werden. Diese ist unter Meine Dienste » Store zu finden.

Es sollte folgende Zip-Datei heruntergeladen und entpackt werden: comuny-workshop-blog.zip (Passwort: comuny)

Für dieses Tutorial werden außerdem ein lokaler Webserver sowie das Grundgerüst benötigt. Beide im Zip-Archiv enthaltenen Dateien im Unterordner comuny-workshop müssen von dem lokalen Webserver unter der Adresse http://localhost/comuny-workshop/index.html ausgeliefert werden. Es ist wichtig, dass die URL exakt übereinstimmt, damit später der Login funktioniert. Wenn alles richtig aufgesetzt ist, sollte beim Öffnen der URL folgendes zu sehen sein:

Nach einem Klick auf den Login-Button, eventuellem Neu-Einloggen bei Zeitüberschreitung und Zulassen der App sollte in der oberen rechten Ecke die comuny-ID des aktuell angemeldeten Nutzers erscheinen.

Das Grundgerüst

Das Grundgerüst besteht aus zwei Dateien, index.html und app.js. Erstere haben wir vorbereitet, sie enthält die Oberfläche und Javascript-Funktionalität, die die Benutzung der API vereinfachen. Diese Datei werden wir nicht verändern, den eigentlichen Code schreiben wir nur in der zweiten Datei. Darin enthalten sind jeweils Funktionen pro Button, welche aufgerufen werden, sobald der Button gedrückt wird. Die Parameter sind dabei die Werte aus den zugehörigen Input-Elementen. Pro Funktion muss ein Aufruf gegen die API implementiert werden. Wir haben für jede verwendete HTTP-Methode (GET, POST, PUT, DELETE) eine Hilfsmethode geschrieben: comunyGet(), comunyPost(), comunyPut(), comunyDelete(). Diese erhalten als ersten Parameter den Pfad des jeweiligen Aufrufs, so wie er auch in der API-Dokumentation angegeben ist. Allen Funktionen außer comunyGet() kann außerdem als zweiter Parameter ein Body-Objekt übergeben werden.

Erstellung eines Contexts

Um Daten in comuny abzulegen, müssen wir zuerst einen Context für sie erstellen. Zu einem solchen Zugriff werden wir später auch andere Nutzer einladen, die dann Zugriff auf alle Daten erhalten, die zu diesem Context gehören.

Dazu müssen wir einen POST-Request gegen https://api.comuny.de/api/contexts schicken. Dadurch wird ein Context angelegt und in der Antwort mitgeschickt. Wir ersetzen also das // TODO in der Funktion createContext wie folgt:

function createContext() {
    comunyPost('contexts', {});
}

Wenn wir nun die Seite neu laden, sollten wir nach einem Klick auf Create Context folgende Antwort auf der rechten Seite sehen:

{
    "id": 65097,
    "ownerid": 51884,
    "organizationid": null,
    "creationTime": "2017-07-18T18:57:02+02:00",
    "expirationDate": "2017-10-16",
    "encryptionType": "AES_128",
    "participants": [
        {
            "id": 65098,
            "personId": 51884,
            "organizationId": null,
            "contextId": 65097,
            "ewsRoleId": null,
            "status": "OK",
            "authority": "EwsContextOwner"
        }
    ],
    "externalInfos": []
}

Damit haben wir unseren ersten Context erstellt.

Auflistung des eigenen Contexts

Um sich nicht alle Context-IDs merken zu müssen, gibt es natürlich auch einen API-Call, um sich alle eigenen anzeigen zu lassen. Dies geschieht durch einen GET-Request gegen https://api.comuny.de/api/persons/contexts/own:

function listContexts() {
    comunyGet('persons/contexts/own');
}

In der Antwort sollte nun ein Array mit einem einzigen Eintrag auftauchen:

[
    {
        "id": 65097,
        "ownerid": 51884,
        "organizationid": null,
        "creationTime": "2017-07-18T18:57:02+02:00",
        "expirationDate": "2017-10-17",
        "encryptionType": "AES_128",
        "participants": [
            {
                "id": 65098,
                "personId": 51884,
                "organizationId": null,
                "contextId": 65097,
                "ewsRoleId": null,
                "status": "OK",
                "authority": "EwsContextOwner"
            }
        ],
        "externalInfos": []
    }
]

Die ID (in diesem Beispiel 65097) sollten wir uns an dieser Stelle merken, da wir sie im nächsten Schritt noch einmal brauchen.

Erstellung eines Payloads

In unserem Fall ist das eigentliche Ziel das Ablegen von Daten und nicht nur die Erstellung eines Contexts. Das passiert nun in diesem Schritt. Es gibt zwei Arten, um Daten abzulegen. Die eine ist ein sogenannter Payload – den wir hier auch nutzen werden –, die andere ein File. Ein Payload beinhaltet nur Text (z.B. JSON, XML oder einfach Plain Text), ein File kann auch binäre Daten enthalten (z.B. Bilder oder PDFs). Letzteres, ein Datei-Upload, wäre eine sehr gute Idee zur Erweiterung unserer CRUD-Anwendung.

Um den Payload zu erstellen, brauchen wir die ID des Contexts, in dem er landen soll, und natürlich den Inhalt. Diese beiden Werte schicken wir im Body mit einem POST-Request gegen https://api.comuny.de/api/payloads:

function createPayload(content, contextId) {
    comunyPost('payloads', {
        payload: content,
        contextId: contextId
    });
}

Die ID haben wir uns im letzten Schritt gemerkt, als Inhalt nehmen wir das altbekannte Lorem Ipsum: Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Nach Eintragen der Parameter und einem Klick auf den „Create Payload“-Button sollte als Antwort nun folgendes auftauchen:

{
    "id": 65099,
    "contextId": 65097,
    "mimeType": null,
    "parent": null,
    "externalInfo": null,
    "orgId": null,
    "url": "/payloads/65099/dad62c9c-2b58-4326-8a3c-0e1f853f12e8/jackrabbit-jndi",
    "creationTime": "2017-07-18T19:14:43+02:00",
    "ownerId": 51884
}

Geschafft. Der Text wurde sicher in comuny abgelegt. Jetzt kann er nur noch vom eigenen Account aus gelesen und gelöscht werden. In dem Fall ist er auch komplett von den Systemen verschwunden, die Datenhoheit liegt vollständig beim Benutzer.

Auflistung von Payloads eines Contexts

Damit wir uns weiterhin keine IDs merken müssen, können auch die Payloads aufgelistet werden. Dies machen wir mit einem einfachen GET-Request gegen https://api.comuny.de/api/payloads?contextid=65097:

function listPayloads(contextId) {
    comunyGet('payloads?contextid=' + contextId);
}

Antwort:

[
    {
        "payload": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "registryEntryId": 65099,
        "error": false,
        "errorCode": null
    }
]

Anzeigen von RegistryEntry und Payload

In der Antwort steht neben dem Inhalt eines Payloads zusätzlich die ID des jeweiligen RegistryEntry. Dieser beinhaltet einige Metadaten, z.B. einen Mime-Type oder den Zeitpunkt der Erstellung. Abrufen können wir ihn per GET gegen https://api.comuny.de/api/registryEntry/65099:

function viewRegistryEntry(registryEntryId) {
    comunyGet('registryEntry/' + registryEntryId);
}

In der Antwort finden wir auch die URL des Payloads:

{
    "id": 65099,
    "contextId": 65097,
    "mimeType": null,
    "parent": null,
    "externalInfo": null,
    "orgId": null,
    "url": "/payloads/65099/dad62c9c-2b58-4326-8a3c-0e1f853f12e8/jackrabbit-jndi",
    "creationTime": "2017-07-18T19:14:43+02:00",
    "ownerId": 51884
}

Darüber können wir ihn direkt abrufen:

function viewRegistryEntry(registryEntryId) {
    comunyGet('registryEntry/' + registryEntryId);
}

Antwort:

{
    "payload": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
}

Ausblick

Im zweiten Teil dieser comuny-API Dokumentation werden wir unsere CRUD-Anwendung fertig stellen. Dazu implementieren wir das Bearbeiten und Löschen von Payloads, sowie das Löschen eines Contexts. Als Bonus lernen wir außerdem, wie man weitere Nutzer zu einem Context hinzufügen oder entfernen kann, um Daten mit ihnen zu teilen.

(Paul Gerste)

In unserer Reihe synTechTalk geben unsere DEV und OPS Teams Einblicke in ihr Technologie- und Architektur-KnowHow zur Umsetzung erfolgreicher digitaler Geschäftsmodelle.

Keine Kommentare