3. Grundlagen

Owned by Frank Sprenger
Last updated: Apr 29, 2022
2 min read

Die nachfolgende Seiten geben eine schnelle Einführung in den Grundlagen der Sage 100 APIs. Manche Aspekte, wie z.B. das HTTP Protokoll oder die REST Prinzipien, können von erfahrenen Entwickler übersprungen werden. Sage 100 spezifische Informationen sollten jedoch unbedingt gelesen und angewendet werden.

Prinzipien

Das HTTP-Protokoll definiert die Grundlagen der Kommunikation mit einer API. Darüber hinaus ist jedoch nicht definiert, wie zum Beispiel eine URL mit ihren Segmenten exakt aufgebaut ist und auch nicht die Bedeutung der einzelnen Segmente oder Query-Parameter oder der Aufbau des Payloads. Hier kommen die Prinzipien und Konventionen des SData Protokoll ins Spiel. Es erweitert das HTTP-Protokoll um Semantik und einzuhaltende Konventionen. Die Sage 100 API basiert prinzipiell auf dem SData-Protokoll, bringt aber viele Erweiterungen und Einschränkungen mit sich.

Die Sage 100 API folgt REST Prinzipien.

  • Sämtlich Client/Server Interaktion erfolgt über das HTTP-Protokoll.

    • Operationen werden über HTTP-Verben (GET, PUT, PATCH, POST, DELETE) abgebildet.

    • Zusätzlich notwendige Informationen werden über HTTP-Header übertragen. Z.B. für Autorisierung oder die Kompression der Nutzlast.

  • Die Client/Server Kommunikation ist zustandslos. D.h. zwischen unterschiedlichen Anfragen werden keine Client-Informationen gespeichert.

  • Über HTTP-Statuscodes teilt der Server dem Client mit, ob die Anfrage erfolgreich bearbeitet wurde.

Versionierung

Die API's sind versioniert. Die Versionierung folgt dem "Semantic Versioning" und hat das Format [Major].[Minor].[Patch]. Beispiel: 1.0.0. Die Version der in der Kunden-Installation bereitgestellten APIs können über Intermediate Requests abgefragt werden.

  • Eine geändert Major-Version zeigt an, dass diese Version inkompatibel zur vorherigen Version ist. Dies ist Beispielsweise der Fall, falls Felder oder Ressourcen gelöscht wurden, Felder zu Pflichtfelder oder umbenannt wurden oder aber bei einer nicht zu erwartenden Verhaltensänderung.

  • Die Minor-Version wird erhöht, wenn die API zusätzliche Features enthält, aber noch kompatibel zur vorherigen Version ist. Z.B. neue Ressourcen oder zusätzliche Felder.

  • Eine Erhöhung der Patch-Version erfolgt bei Bugfixes.

Eine Version der Anwendung stellt immer genau eine Version der API zur Verfügung. API's können über mehrere Version der Anwendung kompatibel bleiben, müssen es aber nicht.