3.6. Operationen auf einer Ressource
Lesen einer Ressource
Das Lesen einer Ressource (also eines Datensatzes) erfolgt über eine GET Operationen mit einer Url, die die Ressource eindeutig identifiziert.
Die Anfrage
GET https://[baseurl]/sdata/ol/apiKunden.Sage.API/OLDemoReweAbfD;123/eptKunden.Sage.API('NDM=;RDEwMDAwMA==')
Accept: application/json
prefer: compact,shrinked
Authorization: Bearer *****liefert folgendes Ergebnis im Body
{
"$key": "NDM=;RDEwMDAwMA==",
"$etag": "AAAAAAADQ/o=;AAAAAAAIFl8=",
"CustomFields": [
{
"Name": "KHKKontokorrent_USER_MyCustomField",
"Value": 1
}
],
"Kto": "D100000",
"Matchcode": "Arber, Sauerlach",
"Besteuerung": 1,
"EUUStID": null,
"Zahlungskond": "BEZ Kunde",
"Preiskennzeichen": -1,
"Gruppe": "WVI",
"Anrede": "Herrn",
"LieferLand": "DE",
"LieferOrt": "Sauerlach",
"LieferPLZ": "82054",
"LieferStrasse": "Wagnergasse 3",
"AdressenMatchcode": "Arber, Sauerlach",
"Name1": "Franz Arber",
"Name2": "Großhändler",
"A1Besteuerung": 0
}
Um einen Datensatz zu ändern, muss dieser (über ein GET auf die einzelne Ressource oder eine Query) vorher gelesen werden, da der ETag-Wert benötigt wird.
Update einer Ressource
Eine Update einer Ressource kann über eine PUT oder PATCH Operation erfolgen. Während bei PATCH lediglich die geänderte Daten im Body übertragen werden müssen, ist es bei einer PUT Operation erforderlich alle, also auch unveränderte Daten, zu übertragen.
Bei diesen Operation ist es zusätzlich erforderlich den gelesenen ETag-Wert im 'If-Match' Header zu senden. Dieser dient zur Überprüfung, ob in der Zwischenzeit ein Anderer diesen Datensatz geändert hat. Ist dies der Fall, wird die Operation mit dem Http-Statuscode 412 (Precondition Failed) abgewiesen. Im Body der Nachricht schickt der Provider in diesem Fall immer den für ihn aktuellen Datensatz zurück.
Um das Feld ‘LieferStrasse’ des gelesenen Satzes zu ändern, ist folgende Anfrage zu schicken:
PATCH https://[baseurl]/sdata/ol/apiKunden.Sage.API/OLDemoReweAbfD;123/eptKunden.Sage.API('NDM=;RDEwMDAwMA==')
Authorization: Beaser *****
Accept: application/json
Content-Type: application/json
If-Match: AAAAAAADQ/o=;AAAAAAAIFl8=
{
"LieferStrasse": "Wagnergasse 5"
}War die Operation erfolgreich, antwortet der Provider mit dem Http-Statuscode 200 (ok). Im Body der Antwort wird die geänderte Ressource zurück geliefert.
Falls es nicht erforderlich ist, den geänderten Datensatz zurück geliefert zu bekommen, kann man dies über die Angabe das Http-Headers 'Prefer: return=minimal' erreichen. In diesem Fall liefert der Provider bei Erfolg den Http-Statuscode 204 (No Content) und einen leeren Body.
Neue Ressource erstellen
Eine neue Ressource wird über die POST Operation erzeugt. Im Body der Anfrage müssen zumindest die erforderlichen Felder geschickt werden. Welche dies sind, ist aus der Referenz-Dokumentation zu entnehmen. Über die Template-Url kann man (muss man aber nicht) die Default-Werte für eine neue Ressource vorher ermitteln.
Die Aufgabe einen Schlüssel für die Ressource zu erzeugen liegt bei den Provider. In den meisten Fällen ist es aber für den Client möglich, einen Wert für den Schlüssel über eine Angabe im Body vorzuschlagen. Dies ist, nochmals, nicht bindend für den Provider.
Wenn die Anfrage erfolgreich bearbeitet wurde, enthält die Antwort im Body die Daten der neuen Ressource, so wie sie von Provider gespeichert wurde.
Löschen einer Ressource
Über eine DELETE Operation wird eine Ressource gelöscht. Die Ressource wird durch die Eindeutigkeit der URL bestimmt; es wird kein Body mitgegeben weder in der Anfrage noch in der Antwort einer erfolgreichen Bearbeitung.