/
3.1. HTTP-basierte Kommunikation

3.1. HTTP-basierte Kommunikation

Owned by Frank Sprenger
Last updated: Apr 13, 2022 by Mayer, Wolfram
5 min read

Die Kommunikation mit den Sage 100 APIs findet über HTTPS statt. HTTP ist das Protokoll das den Interaktionen im Internet unterliegt und daher sowohl vertrauenswürdig als auch flexibel genug ist, um einen sicheren Zugang zu Sage 100 Informationen zu gewähren.

HTTP-basierte Interaktionen erfolgen nach einen Anfrage-Antwort Muster. Der Anforderer (von hier an Client genannt) stellt eine Anfrage für Daten an eine Applikation. Die Applikation (auch Provider oder Server genannt) analysiert und validiert die Anfrage und dann liefert einen Status (wenn alles gut geht) und die angeforderte Daten.

HTTP ist eigentlich ganz einfach (Details siehe unten):

  • Die Url identifiziert ein Entity, ein “Ding” wie z.B. einen Kunden oder einen Beleg

  • Das Verb definiert die Aktion, die auf diesem “Ding” ausgeführt werden soll.

  • Im Body oder Payload werden die Daten des “Dings” transportiert

  • Im Header werden zusätzliche Parameter mitgeschickt, die der Provider benötigt oder ihn steuert.

  • Als Ergebnis liefert der Provider noch einen Status, der angibt, ob die Operation erfolgreich war

Die URL

Die URL erfüllt zwei Aufgaben:

  • identifiziert einen Ressourcentyp

  • überträgt zusätzliche Parameter an den Provider

Betrachtet man die URL

https://www.example.com:5407/questions/3456/my-documents?startindex=10&count=40

so kann man die folgende Bestandteile identifizieren:

  • https:// - definiert das Protokoll dessen Form die Anfrage folgt. In diesen Falls ist es HTTP-Secure, das Protokoll dass die Sage 100 APIs verwenden.

  • www.example.com:5407 - spezifiziert um welche Internet Adresse / Domäne es sich handelt - www.example.com - und auf welchem Port die Anfrage gestellt wird - 5407 in diesen Fall.

  • questions/3456/my-documents: ist eine Folge von URL Segmenten (Segmente werden durch '/' von einander getrennt) die einen hierarchischen Pfad bilden an derem Ende das Ziel steht. Dieses kann eine einzelne oder eine Gruppe von Ressourcen sein - in unserem Fall, 'my-documents' ist den Namen nach, eine Gruppe von Dokumenten.

  • ?count=40&skip=10: der sogenannte Query String der eine durch '&' getrennte Liste von Namen-Wert Parameter ist. Hier sind 'startindex' und 'count' spezifiziert. HTTP definiert keine Normierung der Parameter und deren Bedeutung.

Header

Header liefern zusätzliche Informationen über Eigenschaften und Bedingungen einer Anfrage. Es gibt eine ganze Reihe von Header die von HTTP vorgesehen sind. Jede Applikation kann aber auch zusätzlich eigen-definierte Header verwenden. Die am häufigsten verwendeten Header sind:

  • “Accept”: Komma separierte Liste, drückt aus in welche Formate (ex:JSON, XML, YAML) die Antwort einer Anfrage zu formulieren ist. Da die Sage 100 API primär mit JSON operiert, muss der Wert immer “application/json” sein.

  • “Authorization”: Liefert die Authorisierungsmethode und notwendigen Daten zu Authentifizierung.

  • “If-Match”: Komma separierte Liste von Etags - Etags sind eindeutige Stempel die die Version einer Ressource identifizieren. Die Anfrage wird nur dann vom Provider ausgeführt wenn ein Etag aus der Liste mit dem aktuellen Etag der Ressource übereinstimmt.

Anfrage Verben

Der HTTP Protokoll definiert eine kleine Anzahl an Verben (manchmal auch Methoden oder Operationen genannt) die eine grundsätzliche Bedeutung haben. Die in der Sage 100 API verwendeten sind:

  • GET: holt (eine oder mehrere) Ressourcen

  • POST: erzeugt eine neue Ressource (in den meisten Fällen)

  • PUT/PATCH: verändern die Inhalte einer Ressource

  • DELETE: entfernt eine Ressource

GET

GET fragt Daten vom Provider ab. Per Definition, kann eine GET-Anfrage keinen Body enthalten.

Das Ergebnis einer solchen Anfrage kann eine einzelne Ressource oder aber eine Liste mit Ressourcen sein. Dies wird über die URL spezifiziert.

Für die URL:

https://www.example.com:5407/questions/3456

würde der Provider gewöhnlicherweise das Ziel als 'vom der Ressourcentyp 'questions' die Ressource mit Schlüssel '3456' interpretieren. Entsprechend würde die Methode eine einzelne Ressource liefern.

GET kann auch eine Menge an Ressourcen liefern - wir werden diese Form von GET Query nennen. Hätten wir den letzten Segment (/3456) weggelassen so würde der Pfad auf 'questions' zeigen und dann würde der Provider aufgefordert alle 'question' Ressourcen zu liefern. Der Query String kann helfen die Menge (die kann erheblich groß sein) einzuschränken.

Die URL

https://www.example.com:5407/questions/3456/my-documents?startindex=10&count=40

würde, für einen Sage 100 Provider, diese so interpretieren: von allen Ressourcen die selektiert worden sind, starte mit dem 10ten Satz (startindex) und liefere die folgenden 40 Sätze (count). Dadurch ist es möglich mit größere Ergebnismengen umzugehen.

POST

POST dient primär dazu eine Ressource zu erzeugen, also einen Datensatz anzulegen. Die Inhalte werden in den Body der Anfrage geliefert - der meistens als eine hierarchisch strukturierte Gruppe von Namen-Wert Paare aufgebaut ist.

Die Aufgabe einen Schlüssel für die Ressource zu erzeugen liegt bei dem Provider. In den meisten Fällen ist es 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.

PUT und PATCH

Die PUT und PATCH Verben sind für die Änderung der Daten einer einzelne Ressource vorgesehen. Daher muss die URL einer solchen Anfrage genau eine Ressource adressieren. Der Body der Anfrage beinhaltet zumindest die Namen-Werte Paare der Änderungen. Die im Body enthaltene Daten sind unterschiedlich für PUT und PATCH:

  • PUT: alle Daten (geändert oder nicht) müssen zur Verfügung gestellt werden

  • PATCH: nur die Änderungen sind im Body enthalten

Im Falle einer erfolgreichen Bearbeitung, werden die Daten der geänderten Ressource zurück geliefert.

DELETE

Das intuitivste Verb: Es bezieht sich auf genau eine Ressource und löscht diese. Die Ressource wird durch die Eindeutigkeit der URL bestimmt; es wird kein Body mitgegeben weder in die Anfrage noch in der Antwort bei einer erfolgreichen Bearbeitung.

Inhalt (Body) einer Anfrage

Die Inhalte (Body) die eine Anfrage begleiten sind einen strukturierten Satz an Namen und die dazugehörigen Werten. Es haben sich sowohl XML (etwas älter) und JSON als unterliegende Body Beschreibungsformalismen durchgesetzt. Die Sage 100 API verwendet ausschließlich JSON. Ein Beispiel (in JSON) einer GET Operation:

https://www.example.com/salesOrders/111

liefert als Ergebnis den Body

{ "id": "111", "orderDate": "2001-07-01", "shipDate": null, "contact": { "id": "216" }, "subTotal": 1553.10 }

Status der Bearbeitung

Der Provider liefert immer den Status der Verarbeitung mit seine Antwort mit. Der HTTP Status ist ein standardisierter, numerischer Code der in Intervalle von 100 unterteilt ist.

Die Wichtigsten bei der Verwendung der Sage 100 API sind:

  • 2xx Bereich: Erfolgreiche Operation

    • 200 (OK) : Die Anfrage wurde erfolgreich bearbeitet und das Ergebnis der Anfrage wird in der Antwort übertragen.

    • 201 (Created): Die Ressource wurde erstellt

    • 204 (No Content): Die Anfrage wurde erfolgreich bearbeitet. Es wurde bewusst kein Body geliefert

  • 4xx Bereich: Client Fehler; Die Ursache des Scheiterns der Anfrage liegt (eher) im Verantwortungsbereich des Clients.

    • 400 (Bad Request): Die Anfrage ist falsch formuliert.

    • 401 (Unauthorized): Die Autorisierung für die Anfrage ist nicht ausreichend

    • 403 (Forbidden): Der Client ist nicht berechtigt

    • 404 (Not Found): Die durch die URL adressiert Ressource kann nicht gefunden werden

    • 409 (Conflict): Die Anfrage wurde unter falschen Annahmen gestellt. Im Falle einer PUT-Anfrage kann dies zum Beispiel auf eine zwischenzeitliche Veränderung der Ressource durch Dritte zurückgehen.

    • 410 (Gone): Die angeforderte Ressource wird nicht länger bereitgestellt und wurde dauerhaft entfernt.

  • 5xx Bereich: Provider Fehler

    • 500 (Internal Server Error): Interner Provider/Server Fehler

    • 503 (Service Unavailable): Der Server steht temporär nicht zur Verfügung. Der Client kann die Anfrage zu einem späteren Zeitpunkt wiederholen.

Related content