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. 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 durch den vollständigen Body der Ressource (oder, wenn der Endpunkt-Vertrag es zulässt, durch einen partiellen Body, der nur die zu ändernden Teile enthält). Welcher Endpunkt PATCH unterstützt und ob ein PUT ein vollständiges oder partielles Ersetzen ist, 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 dem Konfliktfehler WGL409005 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) 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.