OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle
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/auftraegepasst 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.
- Verbindung. Klartext an einen TLS-Port: 400 als
text/plain, die Verbindung wird geschlossen. - Anfragezeile. Keine gültige HTTP-Methode: 400
text/plain„Ungültige Anfragezeile.“, die Verbindung wird geschlossen. - OPTIONS. CORS-Preflight, immer 204. Keine weitere Prüfung.
- Anfragegrenze. Grenze überschritten: 429
RATE_LIMITED. - Andrang. Zu viele gleichzeitige Anfragen am Server-Profil: 503
SERVICE_UNAVAILABLE. - API-Key und Zugang. Key unbekannt: 401
API_KEY_INVALID. Zugang inaktiv oder Anfrage nicht vom erlaubten Host: 403. Client-Zertifikat passt nicht: 401CLIENT_CERT_INVALID.Originnicht erlaubt: 403. - 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_EXPIREDoderAUTH_FAILED. Das gilt auch für unbekannte Pfade. - Endpunkt. Kein Template passt: 404
NOT_FOUND. Zugang hat keine Berechtigung für den Endpunkt: 403. - Körper. Gepackter Körper defekt: 400. Zu groß: 413. Codierung nicht unterstützt: 415.
- Idempotenz. Nur schreibende Methoden.
Idempotency-Keyfehlt: 400IDEMPOTENCY_KEY_MISSING. Bekannter Key: gespeicherte Antwort, 422, 503 oder 409, siehe Idempotenz. - 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. - Datei. Bei einer Dateiantwort wertet der Server
Rangeaus: 206 oder 416. - Antwort. Der Server setzt
X-Trace-Idund packt die Antwort bei Bedarf.
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,PATCHundDELETE. Ohne Header: 400IDEMPOTENCY_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-datazählt derboundary-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-Encodingselbst 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.