Konventionen

Diese Seite fasst die HTTP-Konventionen an einem Ort zusammen, die beim Aufruf der WEEGLOO-API aus Code für alle Requests und Responses gemeinsam gelten. Dazu gehören der Medientyp der Response, partielle Änderungen (JSON Patch) und der Header X-Weegloo-Version, der Konflikte bei gleichzeitigen Änderungen verhindert. Die Endpunkte einzelner Ressourcen werden in der jeweiligen Ressourcen-Referenz behandelt; für die Konventionen, denen diese Endpunkte gemeinsam folgen, verweisen sie auf diese Seite.

Medientyp der Response

Die Responses der WEEGLOO-API verwenden den Medientyp application/vnd.com.weegloo.v1+json;charset=UTF-8. Es ist nicht das gewöhnliche application/json.

Senden Sie im Request kein Accept: application/json. Wird der Medientyp über diesen Wert ausgehandelt, passt er nicht zum Vendor-Typ von WEEGLOO und kann zu Fehlern wie 406 Not Acceptable führen.

• Empfohlen: Lassen Sie den Header Accept im Request weg (z. B. kein Accept bei fetch).
• Wenn Sie ihn unbedingt senden müssen, verwenden Sie denselben Vendor-Typ wie die Response: application/vnd.com.weegloo.v1+json;charset=UTF-8.

Achten Sie beim Erstellen einer axios-Instanz oder eines gemeinsamen fetch-Wrappers darauf, dass der Standardwert nicht Accept: application/json erzwingt. (Diese Regel gilt für Anwendungscode. KI-Agenten rufen HTTP nicht direkt auf, sondern verwenden MCP-Tools.)

Partielle Änderung (JSON Patch)

Die meisten Ressourcen wie Content, Media und Content Type lassen sich mit PATCH teilweise gezielt ändern. Der Body ist ein Array im Format RFC 6902 JSON Patch (wird in einem neuen Tab geöffnet). Jeder Eintrag hat die Operation op, den JSON-Pointer-Pfad path, der die Zielposition angibt, und je nach Operation value oder from.

Der Header Content-Type eines PATCH-Requests muss application/json-patch+json sein. Es ist nicht das gewöhnliche application/json.

Das folgende Beispiel ändert nur den Wert eines einzelnen Feldes.

[
  { "op": "replace", "path": "/fields/price/en-US", "value": 16500 }
]

Um den gesamten Body zu ersetzen, verwenden Sie PUT. PUT ersetzt immer die gesamte Ressource; Werte, die Sie im Body weglassen, werden gelöscht. Welcher Endpunkt PATCH unterstützt, prüfen Sie im Endpunkt-Block der jeweiligen Ressourcenseite.

Nebenläufigkeitskontrolle (X-Weegloo-Version)

Wird dieselbe Ressource an zwei Stellen gleichzeitig geändert, kann eine Änderung die andere überschreiben. Um dies zu verhindern, verwendet WEEGLOO optimistische Nebenläufigkeitskontrolle. Beim Ändern, Löschen oder Statuswechsel einer Ressource wird die aktuelle sys.version im Header X-Weegloo-Version mit dem Request gesendet.

Der Server akzeptiert die Änderung nur, wenn dieser Wert mit der gespeicherten aktuellen Version übereinstimmt. Fehlt der Header oder weicht der Wert ab (etwa weil zwischenzeitlich jemand anderes zuerst geändert und damit die Version erhöht hat), wird der Request mit einem Konfliktfehler abgelehnt. In diesem Fall fragen Sie die Ressource erneut ab, um die aktuelle sys.version zu erhalten, und wiederholen die Änderung. Das Format der Fehlerantwort wird unter Fehler behandelt.

Welche Requests den Header benötigen, zeigt die folgende Tabelle.

Ressourcen ohne version (ServiceUser, Scheduler), Änderungen an einem Delivery Access Token oder Space Access Token sowie Requests an ACMA nehmen diesen Header nicht an. Welcher Endpunkt genau diesen Header verlangt, prüfen Sie im requestHeaderSchema im Endpunkt-Block der jeweiligen Ressourcenseite. Die Bedeutung von sys.version selbst wird unter Systemeigenschaften (sys) behandelt.

Verwandte Dokumente

• Systemeigenschaften (sys): die sys.version, die in X-Weegloo-Version mitgesendet wird.
• Gemeinsame Query-Parameter: Listenabfrage und Paginierung.
• Fehler: Fehlercodes wie WGL409005.