14 v.App und v.Api

Mit den Update-Funktionen in der v.Api kannst du bestimmte Datensätze vollständig oder teilweise aktualisieren.

Die Update Funktionen in der v.Api sind immer als Http-PUT Funktionen ausgeführt. Funktionen, die als Http-POST gekennzeichnet sind können zwar unter Umständen im Einzelfall auch Daten ändern, sind aber keine Update-Funktionen und deswegen intern anders aufgebaut.

v.Api – Aktualisieren von Daten über Http-PUT

Inhalt

1. Aufbau der Update-Funktionen
   • Http-PUT: Query
   • Http-PUT: Body
   • Http-PUT: Auth
   • Http-PUT: Response
2. Datenintegrität sicherstellen mit dem X-Hash Header
   • Motivation
   • Bilden des Hashwertes
   • Validieren des Hashwertes
3. Empfohlene Vorgehensweise für das Aktualisieren

1. Aufbau der Update-Funktionen

Http-PUT: Query

Der Query einer Update-Funktion ist immer im Schema PUT /api/Datentyp/{id} aufgebaut.
Als {id} musst du die ID des Datensatzes angeben, den du aktualisieren möchtest. Die ID ist der Primärschlüssel des Datensatzes in v.Soft.

Je nach Datentyp kann das ein String, ein Int oder eine Guid (UUID) sein.

Http-PUT Query für das Ticket T11000

Http-PUT: Body

Die eigentlichen Daten werden der PUT-Methode als JSON-Body übergeben.

Bitte beachte: Auch die Daten, die du nicht ändern möchtest, müssen im JSON-Body übergeben werden. Die Api nimmt sonst an, dass du diese auf NULL setzen möchtest. Am einfachsten ist es deshalb, sich vor jeder PUT Methode die aktuellen Daten des Datensatzes per GET Methode zu holen.

Die empfohlene Vorgehensweise für das Aktualisieren über die Http-PUT Methoden ist deshalb:

1. Abfrage der aktuellen Daten über Http-GET
2. Aus dem Ergebniss den JSON-Body bilden. Datenfelder die readonly sind können weggelassen werden
3. Die Daten die geändert werden sollen im JSON-Body aktualisieren
4. Nun die Http-PUT Methode mit dem JSON-Body aufrufen der in den vorherigen Schritten generiert wird

Übertragen der Daten im Body als JSON-String. Die Daten wurden vorher über die Http-GET Funktion abgefragt.

Http-PUT: Auth

Wie bei allen Funktionen muss der Http-PUT Methode ein gültiger JWT-Token als Authentifizierung als AUTH Bearer-Token hinterlegt werden. Bitte beachte außerdem, dass die Update-Funktionen immer auch das entsprechende Recht des Benutzers in v.Soft erfordern. Der JWT-Token muss deswegen mit dem entsprechenden Claim für die Update-Funktion ausgestattet sein.

Http-PUT: Response

Die Update bzw. Http-PUT Methoden antworten mit den folgenden HTTP-Statuscodes:

• 204 – No content: Die Aktualisierung bzw. das Update war erfolgreich.
• 400 – Bad request: Update nicht erfolgreich. Der Grund wird als Nachricht mitgegeben.
• 401 – Unauthorized: Der JWT-Token ist ungültig oder nicht vorhandenen.
• 403 – Forbidden: Dem Benutzer fehlt entsprechende Recht in v.Soft für das aktualisieren des Datensatzes.
• 409 – Conflict: Der Datensatz ist gerade in Bearbeitung oder es kam zu einer Parallelitätsverletzung.

Http-Responses einer PUT-Methode. Die Funktion kann nur mit dem Claim“TicketChange“ im JWT-Token ausgeführt werden

2. Datenintegrität sicherstellen mit dem X-Hash Header

Motivation

Wie oben beschrieben empfehlen wir dir, vor jeder Http-PUT Methode die aktuellen Daten über Http-GET abzufragen. Wenn die GET und die PUT allerdings zeitlich weiter auseinanderliegen besteht die Gefahr, dass ein anderer Benutzer die Daten in der Zwischenzeit verändert hat. Würde man die Http-PUT nun einfach ohne Prüfung ausführen, würde man die geänderten Daten des anderen Benutzers unter umständen wieder mit den alten Daten überschreiben.

Dieses Verhalten nennt man Parallelitätsverletzung.

In v.Soft stellt die Datenbank über Transaktionen sicher, dass es zu keinen Parallelitätsverletzung kommt. Da die v.Api zustandslos arbeitet ist dieser Weg hier nicht möglich. Stattdessen erlauben es die Http-PUT Methoden, einen Hash der Originaldatei im Header mit zusenden. Die v.Api kann dann über den Hash prüfen, ob sich an den Originaldatei in der Zwischenzeit etwas verändert hauptsächlich

Bilden des Hashwertes

Den Hash der Originaldaten kannst du auf zwei Arten bilden bzw. abfragen:

1. Hashwert über die v.Api abfragen:
   Dazu kannst du die entsprechende Http-HEAD des Datensatzes nutzen. Im Response-Header erhältst du den Hash direkt via X-Hash
2. Hashwert selbst erzeugen:
   Frage die Daten dazu über Http-GET ab. Anschließend kannst du einen SHA1-Hash über den kompletten Response-Body bilden. Bitte achte darauf, dass du UTF-8 als Zeichencodierung verwendest.

Http-HEAD liefert den Hash-Wert der Daten

Falls du den Hashwert selber erzeugen möchtest kannst du die Funktion /api/Test/Hash der Api verwenden um zu testen, ob deine Hash-Funktion den selben Wert liefert wie die Hash-Funktion der v.Api.
Die Funktion zeigt dir Beispieldaten und den Hashwert, den die v.Api dafür generiert. Deine Funktion zum erzeugen des SHA1-Hashwertes sollte den selben Hashwert liefern wie diese Funktion.

Funktion zum Test deiner Hash-Funktion. Bei den gegebenen Daten bildet die v.Api den folgenden Hash-Wert

Validieren des Hashwertes

Den Hashwert den du manuell erzeugt oder über die Api abgefragt hast kannst du bei der nächsten Http-PUT mitschicken. Benutze dafür den optionalen X-Hash Header. Wenn du einen Hashwert mitschickst, prüft die Api vor dem Update, ob sich an den Daten des Datensatzes etwas geändert hat. Dazu simuliert die v.Api intern einen Http-GET Methode, bildet den Hashwert und vergleicht diesen mit dem Hashwert, den du im X-Hash Header mitgeschickt hast. Falls die Hashwerte sich unterscheiden wird die Update-Funktion nicht ausgeführt und die v.Api liefert dir 409 - Conflict als Ergebnis zurück.

Über X-Hash schicken wir den Hashwert der originalen Daten mit. Die Daten haben sich in der Zwischenzeit geändert, die v.Api antwortet mit 409 – Conflict

3. Empfohlene Vorgehensweise für das Aktualisieren

Die empfohlene vollständige Vorgehensweise (inklusive X-Hash) für das Aktualisieren über die Http-PUT Methoden ist ein GET/PUT-Zyklus, der wie folgt aussieht:

1. Abfrage der aktuellen Daten über Http-GET
2. Aus dem Ergebnis der Http-GET Methode den JSON-Body bilden. Datenfelder die readonly sind können weggelassen werden
3. SHA-Hashwert über diese Daten bilden (oder per Http-HEAD abfragen)
4. Die Daten die geändert werden sollen im JSON-Body aktualisieren
5. Nun die Http-PUT Methode mit dem JSON-Body aufrufen der in den vorherigen Schritten generiert wird. Den Hashwert als X-Hash Header mitgeben
6. Ergebnis der Http-PUT auswerten
7. Falls 409 – Daten neu abfragen, Benutzer warnen oder Update abbrechen