Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle: Unterschied zwischen den Versionen

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
Neue Seite: HTTP-Vertrag des REST-Servers (Adressierung, Kopfzeilen, Ablauf, Fehlerformat, Fehlercodes, Rate-Limit, Idempotenz)
 
MINERVA-Rademacker (Diskussion | Beiträge)
K MINERVA-Rademacker verschob die Seite OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle nach OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle: Titel an Überschrift angeglichen (REST-Server, Umlaute, sprechende Beispieltitel)
(kein Unterschied)

Version vom 17. November 2026, 07:14 Uhr

HTTP-Schnittstelle

Diese Seite beschreibt den HTTP-Vertrag des REST-Servers: Adressen, Kopfzeilen, Statuscodes, Fehlerformat und Wiederholverhalten. Sie richtet sich an Entwickler, die eine App, eine Webseite oder ein Fremdsystem an OBS anbinden. Wer diese Regeln einhält, bekommt doppelte Sendungen, Lastspitzen und Fehler sauber abgefangen.

Adressierung

Eine Adresse besteht aus Host, Port und dem Pfad eines Endpunkts:

https://<host>:<port>/<Pfad>
https://obs.example.com:8443/beispiel/auftraege/4711

Welche Pfade es gibt, legt der Betreiber je Endpunkt im Feld Pfad-Template fest, z.B. /beispiel/auftraege/{nr}.

  • Statische Segmente müssen passen. Groß- und Kleinschreibung spielt dabei keine Rolle.
  • Platzhalter in geschweiften Klammern passen auf jeden Wert. Der Wert geht unverändert an das Skript.
  • Die Zahl der Segmente muss gleich sein. /beispiel/auftraege passt nicht auf /beispiel/auftraege/{nr}.
  • Leere Segmente zählen nicht. Ein Schrägstrich am Ende oder ein doppelter Schrägstrich ändert die Zuordnung nicht.
  • Passen mehrere Templates, gewinnt das mit den meisten statischen Segmenten. Bei Gleichstand ist die Wahl nicht festgelegt.
  • Query-Parameter (?name=wert) haben keinen Einfluss auf die Zuordnung. Der Server reicht sie an das Skript weiter.

Passt kein Template, antwortet der Server mit 404 NOT_FOUND. Details zum Anlegen: Endpunkte.

Kopfzeilen

Anfrage

Header Wann Bedeutung
apikey jede Anfrage API-Key des Zugangs, Feld API-Key. Fehlt der Header, gilt der Zugang mit dem API-Key *. Gibt es keinen, folgt 401 API_KEY_INVALID.
Authorization Zugang mit JWT-Authentifizierung Bearer <Token>. Ablauf: Anmeldung mit JWT.
Idempotency-Key POST, PUT, PATCH, DELETE Pflicht. Kennung des Vorgangs, höchstens 128 Zeichen. Siehe Idempotenz.
Content-Type Anfragen mit Körper Art des Körpers. Den Körper liest der Server als UTF-8. Datei-Uploads senden multipart/form-data.
Content-Encoding optional gzip für einen gepackten Körper. Siehe Kompression.
Accept-Encoding optional gzip: Der Server packt die Antwort, wenn es sich lohnt.
Origin Aufrufe aus dem Browser Muss im Feld CORS-Origin des Zugangs stehen, sonst 403.
Range, If-Range Datei-Download Teilabruf. Siehe Datei-Download.
Content-Range, Upload-Id, Upload-Metadata fortsetzbarer Upload Siehe Datei-Upload.

Header-Werte und Query-Parameter kürzt der Server nach 1024 Zeichen, bevor das Skript sie sieht. apikey, Authorization und Cookies erreichen das Skript nicht.

Antwort

Header Wann Bedeutung
X-Trace-Id jede Antwort außer OPTIONS und den 400-Abweisungen auf Protokollebene Kennung der Anfrage, gleich dem Feld traceId im Fehlerobjekt.
Retry-After 429 und 503 des Servers Wartezeit in Sekunden bis zum nächsten Versuch.
Idempotent-Replay Wiederholung eines Vorgangs true: Die Antwort ist die gespeicherte Antwort des ersten Aufrufs.
Allow 405 Die Methoden, die der Endpunkt anbietet.
Content-Encoding, Vary gepackte Antwort gzip bzw. Accept-Encoding.
ETag, Location wenn das Skript sie setzt Siehe Scripting.
Strict-Transport-Security Server-Profile mit TLS max-age=31536000; includeSubDomains
Access-Control-* erlaubtes Origin CORS-Freigaben. Access-Control-Expose-Headers nennt mindestens X-Trace-Id, ETag, Location und Retry-After.

Methoden und Inhaltstypen

Methode Verhalten
GET ruft die Skriptmethode Get auf
POST, PUT, PATCH, DELETE ruft die gleichnamige Skriptmethode auf. Idempotency-Key ist Pflicht.
OPTIONS CORS-Preflight. Immer 204, ohne API-Key und ohne Skript. Access-Control-Max-Age: 600.

Hat das Skript keine Methode für das Verb, antwortet der Server mit 405 METHOD_NOT_ALLOWED und dem Header Allow.

Antworten mit JSON tragen Content-Type: application/json; charset=utf-8. Den Statuscode einer erfolgreichen Antwort (z.B. 200, 201, 204) setzt das Skript. Dateien liefert der Server mit ihrem eigenen Typ aus, siehe Datei-Download. Anfragekörper ohne Datei dürfen höchstens 10 MB groß sein, sonst folgt 413.

Ein vollständiger schreibender Aufruf:

PUT /beispiel/auftraege/4711 HTTP/1.1
Host: obs.example.com:8443
apikey: abcdef-ghij-klmn-opqr-stuvwx
Authorization: Bearer <Access-Token>
Idempotency-Key: 3f2b8c1e-7d4a-4e9b-9c0f-5a6d2e1b8f47
Content-Type: application/json; charset=utf-8
Accept-Encoding: gzip

{"status": "erledigt"}

Ablauf einer Anfrage

Der Server prüft in dieser Reihenfolge. Die erste Prüfung, die scheitert, bestimmt die Antwort.

  1. Verbindung. Klartext an einen TLS-Port: 400 als text/plain, die Verbindung wird geschlossen.
  2. Anfragezeile. Keine gültige HTTP-Methode: 400 text/plain „Ungueltige Anfragezeile.“, die Verbindung wird geschlossen.
  3. OPTIONS. CORS-Preflight, immer 204. Keine weitere Prüfung.
  4. Anfragegrenze. Grenze überschritten: 429 RATE_LIMITED.
  5. Andrang. Zu viele gleichzeitige Anfragen am Server-Profil: 503 SERVICE_UNAVAILABLE.
  6. API-Key und Zugang. Key unbekannt: 401 API_KEY_INVALID. Zugang inaktiv oder Anfrage nicht vom erlaubten Host: 403. Client-Zertifikat passt nicht: 401 CLIENT_CERT_INVALID. Origin nicht erlaubt: 403.
  7. JWT. Anfragen an den JWT-Endpunkt melden an, erneuern oder melden ab. Verlangt der Zugang JWT, braucht jeder andere Pfad ein gültiges Access-Token: 401 AUTH_REQUIRED, AUTH_EXPIRED oder AUTH_FAILED. Das gilt auch für unbekannte Pfade.
  8. Endpunkt. Kein Template passt: 404 NOT_FOUND. Zugang hat keine Berechtigung für den Endpunkt: 403.
  9. Körper. Gepackter Körper defekt: 400. Zu groß: 413. Codierung nicht unterstützt: 415.
  10. Idempotenz. Nur schreibende Methoden. Idempotency-Key fehlt: 400 IDEMPOTENCY_KEY_MISSING. Bekannter Key: gespeicherte Antwort, 422, 503 oder 409, siehe Idempotenz.
  11. Skript. Das Skript des Endpunkts läuft und setzt den Status. Methode fehlt: 405. Skriptfehler: 500 INTERNAL_ERROR. Prüfungen des Uploads: 400, 413, 415.
  12. Datei. Bei einer Dateiantwort wertet der Server Range aus: 206 oder 416.
  13. Antwort. Der Server setzt X-Trace-Id und packt die Antwort bei Bedarf.
HINWEIS: Anfragen, die in den Schritten 1 bis 10 abgewiesen werden, erreichen das Skript des Endpunkts nicht.

Fehlerformat

Jede Fehlerantwort ist ein JSON-Objekt mit genau einem Element error:

{
  "error": {
    "code": "AUTH_REQUIRED",
    "uid": "Y00E2VTL21",
    "message": "Authentifizierung erforderlich",
    "traceId": "20261117T091233123-00001A"
  }
}
Feld Bedeutung
code Maschinenlesbarer Fehlercode. Werten Sie diesen aus.
uid Interne Referenz für den Support. Nicht auswerten.
message Text für Menschen. Er kann sich ändern. Interne Details stehen nie darin.
traceId Kennung der Anfrage, gleich dem Header X-Trace-Id.

Der code ist stabil; neue Codes können hinzukommen. Behandeln Sie unbekannte Codes nach dem HTTP-Status.

Einzige Ausnahme sind die 400-Abweisungen auf Protokollebene (Klartext an einen TLS-Port, ungültige Anfragezeile). Sie kommen als text/plain ohne JSON, und der Server schließt die Verbindung.

Fehlercodes

Code Status Ursache Empfohlene Reaktion des Clients
BAD_REQUEST 400 Anfrage nicht verarbeitbar, z.B. gepackter Körper defekt oder Upload ungültig Anfrage korrigieren. Nicht unverändert wiederholen.
IDEMPOTENCY_KEY_MISSING 400 Schreibende Anfrage ohne Idempotency-Key Key erzeugen und mitsenden.
API_KEY_INVALID 401 API-Key unbekannt, widerrufen oder abgelaufen Nicht wiederholen. Neuen Key bzw. Zugangscode beim Betreiber anfordern.
CLIENT_CERT_INVALID 401 Client-Zertifikat fehlt oder passt nicht zum Zugang Zertifikat des Clients prüfen lassen.
AUTH_REQUIRED 401 Zugang verlangt JWT, aber kein Token gesendet Anmelden und Access-Token mitsenden.
AUTH_FAILED 401 Anmeldung abgelehnt oder falscher Token-Typ, z.B. Refresh-Token statt Access-Token message anzeigen. Nicht automatisch wiederholen.
AUTH_EXPIRED 401 Token abgelaufen, Sitzung gesperrt oder Erneuern abgelehnt. Auch der Standard für 401 ohne eigenen Code. Mit dem Refresh-Token erneuern. Scheitert das, neu anmelden.
FORBIDDEN_ROLE 403 Zugang inaktiv, falscher Host, Origin nicht erlaubt, keine Berechtigung für den Endpunkt oder Anmeldung abgewiesen. Die Meldung ist immer „Zugriff verweigert“. Nicht wiederholen. Betreiber mit traceId fragen.
NOT_FOUND 404 Kein Endpunkt passt zum Pfad, oder das Skript meldet „nicht gefunden“ Pfad prüfen.
METHOD_NOT_ALLOWED 405 Endpunkt bietet die Methode nicht an Methode aus Allow verwenden.
CONFLICT 409 Fachlicher Konflikt, vom Skript gemeldet Daten neu laden, Vorgang prüfen.
IDEMPOTENCY_UNRESOLVED 409 Ein früherer Versuch mit demselben Key ist ohne Ergebnis geblieben Nicht automatisch wiederholen. Vom Betreiber klären lassen, ob der Vorgang ausgeführt wurde.
PAYLOAD_TOO_LARGE 413 Körper über 10 MB, entpackter Körper zu groß oder Datei über der Grenze des Endpunkts Datenmenge verkleinern oder aufteilen.
UNSUPPORTED_MEDIA_TYPE 415 Content-Encoding außer gzip, gepackter Upload oder Upload an einen Endpunkt ohne Datei-Upload Ungepackt bzw. an den richtigen Endpunkt senden.
RANGE_NOT_SATISFIABLE 416 Range liegt hinter dem Dateiende Größe aus Content-Range übernehmen, neu anfordern.
VALIDATION_FAILED 422 Daten fachlich ungültig, vom Skript gemeldet Daten korrigieren, dann erneut senden.
IDEMPOTENCY_KEY_REUSED 422 Derselbe Key mit anderem Inhalt Für einen neuen Vorgang einen neuen Key erzeugen.
RATE_LIMITED 429 Anfragegrenze überschritten Retry-After abwarten.
INTERNAL_ERROR 500 Fehler im Server oder im Skript Mit demselben Idempotency-Key wiederholen. Bleibt der Fehler, Betreiber mit traceId fragen.
SERVICE_UNAVAILABLE 503 Server-Profil ausgelastet, oder Anmelden bzw. Abmelden gerade nicht möglich Retry-After abwarten, mit demselben Key wiederholen.
IDEMPOTENCY_IN_PROGRESS 503 Ein Aufruf mit demselben Key läuft noch Retry-After abwarten, dieselbe Anfrage erneut senden.
HTTP_<Status> andere Fehlerstatus ohne eigenen Code, vom Skript gesetzt, z.B. HTTP_410 Nach dem HTTP-Status behandeln.

Endpunkt-Skripte können eigene Codes setzen. Fragen Sie den Betreiber nach den Codes seiner Endpunkte.

Anfragegrenze

Der Server zählt Anfragen je Schlüssel in einem festen Zeitfenster. Schlüssel ist der Wert des Headers apikey, ohne Header die IP-Adresse. Alle Geräte mit demselben API-Key teilen sich also einen Zähler.

Grenze Standard Feld am Server-Profil
Zeitfenster 60 Sekunden Rate-Limit-Fenster
Anfragen mit gültigem Zugang je Schlüssel 120 Erfolgsanfragen
Fehlanfragen je Schlüssel 10 Fehlanfragen
Anfragen aller Clients des Server-Profils 600 Anfragen

Als Fehlanfrage zählt nur eine Anfrage, deren Zugang abgewiesen wird: API-Key unbekannt, Zugang inaktiv, falscher Host, Origin nicht erlaubt oder Client-Zertifikat passt nicht. Alle anderen Anfragen zählen als Erfolgsanfrage, unabhängig vom späteren Status. Ein falsches Passwort bei der Anmeldung ist keine Fehlanfrage.

Ist eine Grenze erreicht, antwortet der Server mit 429 RATE_LIMITED. Retry-After nennt die Sekunden bis zum Ende des Fensters.

Unabhängig davon begrenzt max. Anfragen die gleichzeitig laufenden Anfragen eines Server-Profils. Darüber antwortet der Server mit 503 SERVICE_UNAVAILABLE und Retry-After: 2.

Die Werte stellt der Betreiber auf der Registerkarte 2 Rate-Limits des Server-Profils ein, siehe Server-Profile.

Idempotenz

Der Server sorgt dafür, dass ein wiederholter schreibender Aufruf nur einmal wirkt. Ihr Client muss dafür nur einen Schlüssel mitsenden.

  • Pflicht bei POST, PUT, PATCH und DELETE. Ohne Header: 400 IDEMPOTENCY_KEY_MISSING.
  • Ausgenommen sind der JWT-Endpunkt und WebHook-Endpunkte.
  • Ein Key je Vorgang. Erzeugen Sie je Vorgang und Gerät eine UUID. Verwenden Sie sie für alle Wiederholungen dieses Vorgangs unverändert.
  • Geltungsbereich ist Zugang, Methode und Pfad. Derselbe Key an einem anderen Pfad ist ein anderer Vorgang. Beim Pfad zählt Groß- und Kleinschreibung nicht, ein Schrägstrich am Ende ebenso wenig.
  • Gleicher Inhalt heißt: dieselben Bytes im Körper. Bei multipart/form-data zählt der boundary-Wert nicht mit. Ein neuer Trenner bei der Wiederholung ist also erlaubt.
  • Aufbewahrung: Der Server hält gespeicherte Antworten 30 Tage.
Situation Antwort Reaktion des Clients
Erster Aufruf normale Verarbeitung –
Wiederholung, gleicher Inhalt, erster Aufruf war erfolgreich (2xx) gespeicherte Antwort mit Status, Körper und Headern, dazu Idempotent-Replay: true. Das Skript läuft nicht. Antwort wie beim ersten Mal verarbeiten.
Wiederholung, anderer Inhalt 422 IDEMPOTENCY_KEY_REUSED Neuen Key für den neuen Vorgang.
Erster Aufruf läuft noch 503 IDEMPOTENCY_IN_PROGRESS, Retry-After: 5 Abwarten, dieselbe Anfrage erneut senden.
Früherer Aufruf ohne Ergebnis 409 IDEMPOTENCY_UNRESOLVED Nicht automatisch wiederholen, Betreiber fragen.

Gespeichert werden nur erfolgreiche Antworten (2xx) ohne Datei. Endet ein Aufruf mit Status 400 oder höher oder liefert er eine Datei, gibt der Server den Key wieder frei. Eine erneute Sendung mit demselben Key läuft dann wie ein erster Aufruf.

Schreibvorgänge sind atomar

POST, PUT, PATCH und DELETE laufen in einer Datenbanktransaktion. Skript und Idempotenz-Ergebnis werden gemeinsam gespeichert.

  • Status unter 400: Alle Änderungen sind gespeichert.
  • Status 400 oder höher: In der OBS-Datenbank ist nichts geändert. Ihr Client kann den Vorgang gefahrlos korrigieren oder wiederholen.

GET läuft ohne Transaktion.

Kompression

Antworten

Sendet der Client Accept-Encoding: gzip, packt der Server die Antwort mit gzip. Die Antwort trägt dann Content-Encoding: gzip und Vary: Accept-Encoding. Gängige HTTP-Bibliotheken entpacken selbst.

Gepackt wird nur:

  • JSON, XML, JavaScript, SVG und Typen unter text/,
  • ab 1024 Byte,
  • keine Dateien, keine Antworten mit 204, 206 oder 304,
  • nicht, wenn das Skript Content-Encoding selbst setzt.

Der Betreiber kann das Packen am Server-Profil mit keine Kompression abschalten.

Anfragen

Content-Encoding der Anfrage Ergebnis
fehlt oder identity normale Verarbeitung. Körper über 10 MB: 413
gzip Der Server entpackt den Körper, bevor das Skript ihn liest.
gzip, Körper defekt 400 BAD_REQUEST
gzip, entpackt über 10 MB 413 PAYLOAD_TOO_LARGE
gzip, entpackt über das 400fache der gesendeten Größe (mindestens 64 KB) 413 PAYLOAD_TOO_LARGE
anderer Wert, z.B. deflate oder br 415 UNSUPPORTED_MEDIA_TYPE
beliebiger Wert bei einem Datei-Upload 415 UNSUPPORTED_MEDIA_TYPE

Verbindungen

Der Server hält Verbindungen offen (HTTP/1.1 Keep-alive). Ein Client, der mehrere Anfragen nacheinander stellt, spart so den erneuten Aufbau von TCP und TLS.

Grenze Wert Bedeutung
Leerlauf 10 Sekunden Ohne Daten schließt der Server die Verbindung. Das gilt auch während ein Anfragekörper gesendet wird.
Anfragen je Verbindung 100 Danach schließt der Server die Verbindung geordnet.

Eine geschlossene Verbindung ist kein Fehler. HTTP-Bibliotheken bauen sie bei der nächsten Anfrage neu auf.

Fehlersuche mit X-Trace-Id

Speichern oder zeigen Sie bei Fehlern die X-Trace-Id. Mit ihr findet der Betreiber die Anfrage in Protokoll und Statistik, siehe Betrieb und Fehlersuche.

Siehe auch