¿Cómo documentas una integración API?

Respuesta directa

Qué debe cubrir una buena respuesta

Cómo funciona

Un documento de integración es lo que permite a dos equipos construir uno contra otro sin una reunión por campo. Lista cada operación con su propósito, esquemas de solicitud y respuesta con tipos, campos obligatorios, formatos y ejemplos, y las reglas de validación que producen cada error. Indica cómo se autentica el llamador, qué está autorizado a ver, si las operaciones son idempotentes y cómo, cómo paginan las listas, qué significan los códigos de estado y cuerpos de error, qué límites de tasa y tamaño aplican, cómo se versiona el contrato y qué timeouts y reintentos debe adoptar el llamador. OpenAPI legible por máquina con prosa para lo que un esquema no puede expresar es la forma habitual.

Ejemplo

El documento de la API de envíos mostraba POST /shipments con esquema JSON, un ejemplo de payload, el requisito de Idempotency-Key, un 409 para números de seguimiento duplicados con ejemplo de cuerpo, paginación por cursor en GET /shipments, un límite de 120 solicitudes por minuto con las cabeceras que lo informan y la recomendación de reintentar solo 503 con backoff exponencial. El socio integró en una semana con dos preguntas en lugar de las veinte habituales.

Errores frecuentes

• Documentar solo la respuesta del camino feliz y dejar los errores sin definir.
• Publicar nombres de campos sin tipos, formatos ni cuáles son obligatorios.
• Dejar que el documento se desvíe de la implementación porque nada lo comprueba.

Una estructura útil para responder

Responde desde tu propia experiencia.

No memorices un guion: usa solo ejemplos que puedas explicar con honestidad en preguntas posteriores.