Convenciones

Esta página reúne en un solo lugar las convenciones HTTP que se aplican de forma común a todas las solicitudes y respuestas al llamar a la API de WEEGLOO desde código. Aquí se incluyen el tipo de medio de la respuesta, la modificación parcial (JSON Patch) y la cabecera X-Weegloo-Version, que evita conflictos por modificaciones simultáneas. Los endpoints de cada recurso individual se tratan en la referencia de cada recurso, y esos endpoints remiten a esta página para las convenciones que siguen en común.

Tipo de medio de la respuesta

Las respuestas de la API de WEEGLOO usan el tipo de medio application/vnd.com.weegloo.v1+json;charset=UTF-8. No es el application/json habitual.

No envíe Accept: application/json en la solicitud. Si negocia el tipo de medio con este valor, no coincidirá con el tipo de proveedor de WEEGLOO y puede producirse un error como 406 Not Acceptable.

• Recomendado: omita la cabecera Accept en la solicitud (por ejemplo, no incluya Accept en fetch).
• Si necesita enviarla, use el mismo tipo de proveedor que la respuesta, application/vnd.com.weegloo.v1+json;charset=UTF-8, tal cual.

Al crear una instancia de axios o un envoltorio común de fetch, asegúrese de que los valores predeterminados no impongan Accept: application/json. (Esta regla se aplica al código de aplicación. Los agentes de IA no llaman directamente a HTTP, sino que usan las herramientas MCP.)

Modificación parcial (JSON Patch)

La mayoría de los recursos, como Content, Media o Content Type, se pueden modificar parcialmente con PATCH, seleccionando solo una parte. El cuerpo es un array con el formato RFC 6902 JSON Patch. Cada elemento tiene la operación op, la ruta JSON Pointer path que indica la posición de destino y, según la operación, value o from.

La cabecera Content-Type de una solicitud PATCH debe ser application/json-patch+json. No es el application/json habitual.

El siguiente es un ejemplo que cambia solo el valor de un campo.

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

Para reemplazar el cuerpo completo, use PUT. PUT reemplaza por el cuerpo completo del recurso (o, si el contrato del endpoint lo permite, por un cuerpo parcial que contenga solo la parte que se quiere cambiar). Consulte en el bloque de endpoint de la página de cada recurso qué endpoint admite PATCH y si PUT es un reemplazo total o parcial.

Control de concurrencia (X-Weegloo-Version)

Si se modifica el mismo recurso desde dos lugares a la vez, el cambio de uno puede sobrescribir el del otro. Para evitarlo, WEEGLOO usa control de concurrencia optimista. Al modificar, eliminar o cambiar el estado de un recurso, envíe la sys.version actual en la solicitud a través de la cabecera X-Weegloo-Version.

El servidor solo acepta el cambio cuando este valor coincide con la versión actual almacenada. Si falta la cabecera o el valor no concuerda (por ejemplo, cuando alguien lo modificó antes y la versión aumentó entretanto), se rechaza con el error de conflicto WGL409005. En ese caso, vuelva a consultar el recurso para obtener la sys.version más reciente y reintente el cambio. El formato de la respuesta de error se trata en Errores.

A continuación se indica en qué solicitudes es necesaria.

Los recursos sin version (ServiceUser) no aceptan esta cabecera. Para saber exactamente qué endpoint requiere esta cabecera, consulte el requestHeaderSchema del bloque de endpoint de la página de cada recurso. El significado de sys.version en sí se trata en Propiedades del sistema (sys).

Documentos relacionados

• Propiedades del sistema (sys): la sys.version que se envía en X-Weegloo-Version.
• Parámetros de consulta comunes: consulta de listas y paginación.
• Errores: códigos de error como WGL409005.