Conventions

Cette page rassemble en un seul endroit les conventions HTTP communes à toutes les requêtes et réponses lorsque vous appelez les API WEEGLOO depuis du code. Elles concernent le type de média des réponses, la modification partielle (JSON Patch) et l'en-tête X-Weegloo-Version qui prévient les conflits de modification concurrente. Les endpoints de chaque ressource sont traités dans la référence de la ressource correspondante, et ces endpoints renvoient à cette page pour les conventions qu'ils suivent en commun.

Type de média des réponses

Les réponses des API WEEGLOO emploient le type de média application/vnd.com.weegloo.v1+json;charset=UTF-8. Ce n'est pas le type application/json ordinaire.

N'envoyez pas Accept: application/json dans la requête. Négocier le type de média avec cette valeur ne correspond pas au type vendeur de WEEGLOO et peut provoquer des échecs comme 406 Not Acceptable.

• Recommandé : omettez l'en-tête Accept dans la requête (par exemple, ne mettez pas Accept dans fetch).
• Si vous devez absolument l'envoyer, employez tel quel le même type vendeur que la réponse, application/vnd.com.weegloo.v1+json;charset=UTF-8.

Lorsque vous créez une instance axios ou un wrapper fetch commun, faites en sorte que la valeur par défaut n'impose pas Accept: application/json. (Cette règle s'applique au code applicatif. Les agents IA n'appellent pas HTTP directement, ils emploient les outils MCP.)

Modification partielle (JSON Patch)

La plupart des ressources, comme Content, Media ou Content Type, peuvent être modifiées partiellement, en ne sélectionnant qu'une partie, avec PATCH. Le corps est un tableau au format RFC 6902 JSON Patch. Chaque élément comporte l'opération op, le chemin JSON Pointer path qui désigne l'emplacement cible, ainsi que value ou from selon l'opération.

L'en-tête Content-Type d'une requête PATCH doit valoir application/json-patch+json. Ce n'est pas le type application/json ordinaire.

Voici un exemple qui ne modifie que la valeur d'un seul champ.

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

Pour remplacer par le corps entier, employez PUT. PUT remplace par le corps entier de la ressource (ou, lorsque le contrat de l'endpoint l'autorise, par un corps partiel ne contenant que la partie à modifier). Pour savoir quel endpoint prend en charge PATCH, et si PUT est un remplacement total ou partiel, consultez le bloc d'endpoint sur la page de chaque ressource.

Contrôle de concurrence (X-Weegloo-Version)

Si une même ressource est modifiée simultanément à deux endroits, l'une des modifications risque d'écraser l'autre. Pour l'éviter, WEEGLOO emploie un contrôle de concurrence optimiste. Lorsque vous modifiez, supprimez ou changez l'état d'une ressource, transmettez dans la requête la valeur sys.version actuelle via l'en-tête X-Weegloo-Version.

Le serveur n'accepte la modification que lorsque cette valeur correspond à la version actuelle enregistrée. Si l'en-tête manque ou si la valeur ne concorde pas (par exemple lorsque quelqu'un a modifié la ressource avant vous entre-temps et que la version a augmenté), la requête est rejetée avec l'erreur de conflit WGL409005. Dans ce cas, consultez de nouveau la ressource pour obtenir le sys.version le plus récent, puis réessayez la modification. Le format des réponses d'erreur est traité dans Erreurs.

Voici les requêtes pour lesquelles il est nécessaire.

Les ressources sans version (ServiceUser) n'acceptent pas cet en-tête. Pour savoir précisément quel endpoint exige cet en-tête, consultez le requestHeaderSchema du bloc d'endpoint sur la page de chaque ressource. La signification de sys.version lui-même est traitée dans Propriétés système (sys).

Documents connexes

• Propriétés système (sys) : le sys.version transmis dans X-Weegloo-Version.
• Paramètres de requête communs : consultation de listes et pagination.
• Erreurs : codes d'erreur tels que WGL409005.