约定

最后更新：2026年6月22日

本页集中说明从代码中调用 WEEGLOO API 时，所有请求和响应通用的 HTTP 约定。包括响应媒体类型、部分更新（JSON Patch），以及用于防止并发修改冲突的 X-Weegloo-Version 标头。各资源自身的端点在对应的资源参考中说明，而这些端点共同遵循的约定则参考本页。

响应媒体类型

WEEGLOO API 的响应使用 application/vnd.com.weegloo.v1+json;charset=UTF-8 媒体类型，而不是普通的 application/json。

请不要在请求中发送 Accept: application/json。用该值协商媒体类型会与 WEEGLOO 的厂商类型不匹配，可能导致 406 Not Acceptable 之类的失败。

  • 推荐：在请求中省略 Accept 标头（例如在 fetch 中不加 Accept）。
  • 若必须发送，则原样使用与响应相同的厂商类型 application/vnd.com.weegloo.v1+json;charset=UTF-8。

在创建 axios 实例或通用 fetch 封装时，要确保默认值不会强制设置 Accept: application/json。（此规则适用于应用程序代码。AI 智能体不直接调用 HTTP，而是使用 MCP 工具。）

部分更新 (JSON Patch)

Content、Media、Content Type 等大多数资源都可以通过 PATCH 只选取一部分进行修改。请求体是 RFC 6902 JSON Patch 格式的数组。每一项包含操作 op、指向目标位置的 JSON Pointer 路径 path，以及根据操作而定的 value 或 from。

PATCH 请求的 Content-Type 标头必须是 application/json-patch+json，而不是普通的 application/json。

以下是只改变某一个字段值的示例。

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

若要替换整个请求体，则使用 PUT。PUT 会用资源的完整请求体（或在端点契约允许的情况下，仅包含待修改部分的部分请求体）进行替换。哪些端点支持 PATCH、PUT 是整体替换还是部分替换，请在各资源页面的端点块中确认。

并发控制 (X-Weegloo-Version)

如果在两处同时修改同一个资源，一方的更改可能会覆盖另一方。为防止这种情况，WEEGLOO 采用乐观并发控制。在修改、删除或转换资源状态时，需在请求中通过 X-Weegloo-Version 标头携带当前的 sys.version。

服务器仅在该值与已保存的当前版本一致时才接受更改。如果标头缺失或值不匹配（例如其间有人先行修改导致版本号上升等情况），则会以冲突错误 WGL409005 拒绝。此时需重新查询资源以获取最新的 sys.version，然后重试更改。错误响应格式在错误中说明。

各类请求是否需要该标头如下所示。

类别X-Weegloo-Version
修改（PUT）、部分更新（PATCH）需要
状态转换（发布、取消发布、归档、取消归档）需要
创建（POST）不需要
删除（DELETE）部分需要

没有 version 的资源（ServiceUser）不接受该标头。具体哪些端点要求该标头，请确认各资源页面端点块中的 requestHeaderSchema。sys.version 本身的含义在系统属性 (sys)中说明。