Tema: api-design
-
Usar correctamente los códigos de estado HTTP: la primera bifurcación del cliente
Los clientes, las cachés y los agentes deciden únicamente a partir del código de estado si reintentar, recargar o desistir: 201/204 para el éxito con y sin cuerpo, 401 frente a 403 para la falta de autenticación frente a la falta de autorización, 409/412/428 para conflictos y condiciones previas, 429 y 503 con Retry-After para «más tarde». Un 200 con un objeto de error engaña a todos.
-
Los tipos de error legibles por máquina reducen los reintentos perjudiciales de los agentes
Hipótesis: cuando una API devuelve tipos de problema estables con indicaciones de reintento, los clientes automatizados realizan menos reintentos de solicitudes no reintentables y menos escrituras duplicadas que con errores solo en prosa; una comparación propuesta.
-
Retroceder como cliente: Retry-After, las cabeceras RateLimit y presupuestos por host
Cómo debe reaccionar un agente ante respuestas 429 y 503 y ante las cabeceras informativas de límite de tasa: respetar Retry-After al pie de la letra, y si no está presente retroceder de forma exponencial con jitter, leer los campos RateLimit y RateLimit-Policy cuando un servidor los envíe para adelantarse al límite, mantener un presupuesto por host y por clave, y no reintentar nunca una escritura no idempotente sin una clave de idempotencia.
-
Diseñar límites de tasa que protejan el servicio e informen al cliente
Limitar según la identidad que se pueda verificar (cuenta, prefijo de red), usar contadores atómicos en ventanas fijas o deslizantes, responder con 429 y Retry-After, mantener presupuestos separados para lecturas, escrituras y registros, y publicar los límites efectivos.
-
Paginación y claves de idempotencia en la API de Stripe: starting_after, has_more y la ventana de 24 horas
Los endpoints de listado de la API v1 de Stripe paginan con los parámetros de cursor mutuamente excluyentes starting_after/ending_before (limit de 1 a 100, por defecto 10) y un indicador has_more; las bibliotecas cliente incluyen auxiliares de autopaginación para recorrer todas las páginas. Las solicitudes POST pueden llevar un Idempotency-Key cuyo resultado guardado Stripe reproduce durante unas 24 horas, tras las cuales las claves pueden eliminarse. Las solicitudes limitadas por tasa reciben 429 con la cabecera Stripe-Rate-Limited-Reason.
-
Nomenclatura y capitalización consistentes de los campos JSON
Elegir una única convención de capitalización para los nombres de propiedad y aplicarla en todas partes: la guía de estilo JSON de Google y ProtoJSON usan lowerCamelCase, mientras que muchas APIs usan snake_case. Más allá de la capitalización, conviene mantener nombres con significado, los enums como cadenas, las marcas de tiempo como cadenas RFC 3339 y los enteros de 64 bits como cadenas.
-
La especificación Standard Webhooks frente a la cabecera HMAC de Shopify y al token de secreto compartido de GitLab
La especificación Standard Webhooks define las cabeceras webhook-id, webhook-timestamp y webhook-signature, un secreto en base64 con prefijo whsec_ cuyos bytes decodificados son la clave HMAC y una firma v1,<base64> sobre "{id}.{timestamp}.{payload}"; los tokens de firma de GitLab (GitLab 19.0, disponibilidad general en 19.1) la implementan tal cual. Shopify, en cambio, envía en X-Shopify-Hmac-SHA256 un HMAC en base64 del cuerpo sin procesar, y el antiguo X-Gitlab-Token de GitLab es un simple secreto compartido, no un HMAC en absoluto.
-
Validar JSON con JSON Schema
JSON Schema describe la forma permitida de un documento (tipos, claves obligatorias, enumeraciones, formatos, límites) y permite validar entradas en cualquier lenguaje antes de procesarlas; conviene mantener additionalProperties explícito.
-
Diseñar operaciones idempotentes y reintentos seguros
Una operación es idempotente cuando ejecutarla varias veces tiene el mismo efecto que ejecutarla una sola vez; el RFC 9110 establece esto para los métodos HTTP, y una cabecera Idempotency-Key traslada la propiedad a POST. Guardar la clave junto con una huella y el resultado, informar los conflictos con 409 y 422, y eliminar las claves tras un plazo documentado.
-
Llamar a la API de TypeSafe desde un agente: forma de la solicitud, errores, reintentos y fijación de versión
El contrato documentado que necesita un agente para llamar a Jev sin una capa de chat: POST /v1/systemone con una clave Bearer, un estado, un nombre de modelo y un mapa de preguntas tipadas; las respuestas se indexan igual que las preguntas, más un bloque de uso; los códigos 401, 422, 429 y 529 con backoff exponencial; alias que cambian de versión frente a identificadores versionados que no cambian; los valores por defecto del SDK para los reintentos y la skill del agente para agentes de codificación.
-
Modos de simulación (dry-run) para acciones de agentes: mostrar el plan antes del cambio
Dotar a cada herramienta que cambia el estado de un modo que calcula y devuelve el plan concreto (qué objetos, qué campos, cuántos) sin aplicarlo, validar el plan en el lado del servidor cuando el sistema lo permita, exigir que el plan se produzca y se revise antes de la llamada real, y comparar después el resultado real con ese plan.
-
La cabecera Link y los tipos de relación de enlace
El RFC 8288 permite que cualquier respuesta HTTP incluya enlaces tipados en una cabecera Link: <destino>; rel="relación" más los parámetros opcionales anchor, hreflang, type, title y media. Los nombres de relación proceden del registro de la IANA (next, prev, canonical, alternate, describedby, preload) o son URI absolutas para extensiones privadas. Es el modo en que las respuestas no HTML señalan a sus vecinas y en que el código 103 Early Hints indica a un navegador qué obtener por adelantado.
-
HEAD y OPTIONS: qué responden y para qué los usan los clientes
HEAD es GET sin cuerpo: mismo estado y encabezados (Content-Length y Vary pueden omitirse), almacenable en caché, y se usa para verificar enlaces, sondear el tamaño y comprobar la vigencia. OPTIONS pregunta qué opciones de comunicación admite un recurso o el servidor completo (OPTIONS *), se responde normalmente con Allow, no es almacenable en caché, y transporta los preflight de CORS con Access-Control-Request-Method.
-
Verificación de firmas de solicitudes de Slack: X-Slack-Signature, la ventana de repetición de 5 minutos y la regla de los 3 segundos
Slack firma sus solicitudes con el valor v0=<HMAC-SHA256 en hexadecimal> de la cadena "v0:{timestamp}:{raw body}" en la cabecera X-Slack-Signature, junto con X-Slack-Request-Timestamp; el ejemplo de Slack rechaza la solicitud si esa marca de tiempo difiere de la hora local en más de cinco minutos. Además, los slash commands y las cargas interactivas deben confirmarse en un plazo de tres segundos, antes de cualquier procesamiento lento.
-
Diseñar un SDK sobre una API HTTP
Un SDK debería hacer que la llamada correcta sea la llamada fácil: modelos tipados, un único objeto cliente que contiene la configuración, errores uniformes, reintentos con claves de idempotencia, iteradores de paginación y ayudantes para operaciones de larga duración, generados a partir de la descripción de la API cuando sea posible y escritos a mano solo donde la generación no pueda expresar la intención.
-
Diseñar webhooks salientes en los que los receptores puedan confiar
Firmar cada entrega con un HMAC sobre el cuerpo y una marca de tiempo, entregar al menos una vez con reintentos e ids de evento idempotentes, mantener las cargas útiles pequeñas con un enlace para obtener los detalles, y permitir que los receptores verifiquen sin secretos en las URL.
-
Endpoints masivos y el reporte de fallos parciales
Un endpoint masivo tiene éxito o falla como un todo, o bien informa de los resultados por elemento; un único 200 no puede expresar un éxito parcial, por lo que conviene elegir un comportamiento por endpoint, indexar los fallos por posición, limitar el tamaño del lote, y aplicar la autorización y los límites de tasa por elemento.
-
Elegir los códigos de estado HTTP de forma deliberada
Los códigos de estado son lo primero sobre lo que ramifica un cliente: 200/201/204 para el éxito, 304 para lo que no cambió, 400/422 para una entrada incorrecta, 401/403 para credenciales frente a permiso, 404 para lo ausente, 409/412/428 para conflictos y precondiciones, 429/503 para más tarde.
-
Panorama de los protocolos agente a agente: tarjetas de agente A2A, tareas y dónde encaja MCP
Lo que estandariza el protocolo A2A (versión 1.0.0, Linux Foundation) entre agentes independientes: una tarjeta de agente publicada en /.well-known/agent-card.json con capacidades, habilidades, endpoint y esquemas de seguridad; tareas con un ciclo de vida de submitted, working, input-required, auth-required, completed, failed, canceled y rejected; mensajes y artefactos compuestos de partes; enlaces JSON-RPC, gRPC y REST; y la propia explicación de la especificación sobre cómo complementa a MCP.
-
La negociación de Accept-Language y sus límites
Accept-Language transporta una lista ponderada de rangos de idioma (da, en-gb;q=0.8, en;q=0.7); el servidor la compara con los idiomas de los que dispone mediante el filtrado o la búsqueda (lookup) de la RFC 4647, responde con Content-Language y Vary: Accept-Language, y debe recurrir a un valor por defecto sensato cuando la cabecera está ausente (Googlebot no envía ninguna) o es incorrecta (la configuración regional de un dispositivo no es la elección de un lector). Usarla como primera aproximación, no como el único selector.
Legible por máquina: JSON