Convenções

Reúne em um só lugar as convenções HTTP comuns a todas as requisições e respostas ao chamar a API da WEEGLOO a partir do código. Isso inclui o tipo de mídia da resposta, a edição parcial (JSON Patch) e o cabeçalho X-Weegloo-Version, que evita conflitos em edições simultâneas. Os endpoints de cada recurso são tratados na referência do recurso correspondente, e as convenções que esses endpoints seguem em comum estão nesta página.

Tipo de mídia da resposta

As respostas da API da WEEGLOO usam o tipo de mídia application/vnd.com.weegloo.v1+json;charset=UTF-8. Não é o application/json comum.

Não envie Accept: application/json na requisição. Negociar o tipo de mídia com esse valor não corresponde ao tipo de fornecedor da WEEGLOO e pode provocar falhas como 406 Not Acceptable.

• Recomendado: omita o cabeçalho Accept na requisição (por exemplo, não incluir Accept no fetch).
• Se for realmente necessário enviá-lo, use o mesmo tipo de fornecedor da resposta, application/vnd.com.weegloo.v1+json;charset=UTF-8, tal como está.

Ao criar uma instância axios ou um wrapper fetch comum, garanta que o valor padrão não force Accept: application/json. (Esta regra se aplica ao código da aplicação. O agente de IA não chama HTTP diretamente, e sim usa as ferramentas MCP.)

Edição parcial (JSON Patch)

A maioria dos recursos, como Content, Media e Content Type, pode ser editada parcialmente com PATCH, selecionando apenas uma parte. O corpo é um array no formato RFC 6902 JSON Patch. Cada item tem a operação op, o caminho JSON Pointer path que indica a posição alvo e, conforme a operação, value ou from.

O cabeçalho Content-Type da requisição PATCH deve ser application/json-patch+json. Não é o application/json comum.

A seguir, um exemplo que altera apenas o valor de um campo.

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

Para substituir pelo corpo inteiro, use PUT. O PUT substitui pelo corpo completo do recurso (ou, quando o contrato do endpoint o permite, por um corpo parcial que contém apenas a parte a ser alterada). Verifique no bloco de endpoint de cada página de recurso quais endpoints suportam PATCH e se o PUT é uma substituição total ou parcial.

Controle de concorrência (X-Weegloo-Version)

Se o mesmo recurso for editado em dois lugares ao mesmo tempo, uma alteração pode sobrescrever a outra. Para evitar isso, a WEEGLOO usa controle de concorrência otimista. Ao modificar, excluir ou transicionar o estado de um recurso, envie a sys.version atual na requisição por meio do cabeçalho X-Weegloo-Version.

O servidor só aceita a alteração quando esse valor é igual à versão atual armazenada. Se o cabeçalho estiver ausente ou o valor divergir (por exemplo, quando alguém editou antes nesse intervalo e a versão subiu), a requisição é rejeitada com o erro de conflito WGL409005. Nesse caso, consulte o recurso novamente para obter a sys.version mais recente e refaça a alteração. O formato da resposta de erro é tratado em Erros.

Em quais requisições isso é necessário:

Recursos sem version (ServiceUser) não recebem este cabeçalho. Para saber exatamente quais endpoints exigem este cabeçalho, verifique o requestHeaderSchema no bloco de endpoint de cada página de recurso. O significado da própria sys.version é tratado em Propriedades de sistema (sys).

Documentos relacionados

• Propriedades de sistema (sys): a sys.version enviada em X-Weegloo-Version.
• Parâmetros de consulta comuns: listagem e paginação.
• Erros: códigos de erro como WGL409005.