Documentación y estándares de contrato para APIs REST

Documentación centrada en el consumidor (consumer-first)

La documentación centrada en el consumidor describe la API desde la perspectiva de quien la integra: qué necesita para empezar, qué flujos típicos va a implementar, qué respuestas reales verá (éxito y error) y cómo depurar problemas. No es un inventario de endpoints; es una guía de uso que reduce fricción, tickets de soporte y malentendidos de contrato.

Estructura recomendada del portal de documentación

• Inicio rápido: requisitos, base URL por entorno, cómo obtener credenciales, primer request/response completo.
• Autenticación: métodos soportados, cabeceras, scopes/roles, expiración, rotación, ejemplos y errores típicos.
• Recursos y operaciones: referencia por recurso con ejemplos completos y parámetros.
• Flujos típicos: guías “cómo hacer X” (end-to-end), con decisiones y casos borde.
• Errores: catálogo de códigos de error de dominio, cómo reaccionar, reintentos, correlación.
• Changelog y migraciones: cambios, deprecaciones, guía de actualización.
• Contrato (OpenAPI): especificación descargable, ejemplos, esquemas y modelos reutilizables.
• Pruebas de contrato: cómo validar que cliente y servidor siguen alineados.

Guía práctica paso a paso para documentar una API

Paso 1: Define el “camino feliz” de onboarding

Incluye lo mínimo para que alguien haga su primera integración en 10–15 minutos:

• Base URL (producción y sandbox) y cómo elegir entorno.
• Cómo autenticarse (token, cabeceras requeridas).
• Un ejemplo completo: request con cabeceras + body + response realista.
• Cómo obtener soporte: canal, tiempos, qué información adjuntar (por ejemplo, requestId).

curl -X POST "https://api.sandbox.ejemplo.com/v1/orders" \  -H "Authorization: Bearer <token>" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 3f6b2c1a-..." \  -d '{"customerId":"cus_123","items":[{"sku":"SKU-1","qty":2}]}'

Paso 2: Documenta autenticación con foco en operación real

Además de describir el mecanismo, documenta lo que el consumidor necesita para operar sin sorpresas:

• Cómo obtener credenciales (proceso, permisos, scopes).
• Cómo enviar credenciales (cabeceras, formato).
• Caducidad y renovación (expiración, refresh, rotación).
• Errores frecuentes (token inválido, scope insuficiente) y cómo resolverlos.

Paso 3: Describe recursos con ejemplos completos (no fragmentos)

Para cada recurso, incluye:

• Descripción breve del propósito del recurso.
• Campos principales y reglas de validación importantes.
• Ejemplos completos de request/response (con valores realistas).
• Casos de error típicos del recurso (validación, estado inválido, conflicto).

Ejemplo de respuesta realista (evita “foo/bar”):

Continúa en nuestra aplicación.

• Escuche el audio con la pantalla apagada.
• Obtenga un certificado al finalizar.
• ¡Más de 5000 cursos para que explores!

O continúa leyendo más abajo...

Descargar la aplicación

{"id":"ord_10001","status":"processing","customerId":"cus_123","items":[{"sku":"SKU-1","qty":2,"unitPrice":19.99}],"currency":"EUR","createdAt":"2026-01-15T10:12:45Z"}

Paso 4: Añade flujos típicos (guías “cómo hacer”)

Los flujos conectan operaciones y aclaran decisiones. Ejemplos de flujos útiles:

• Crear pedido → consultar estado → manejar fallo de pago → reintentar.
• Subir documento → esperar procesamiento → obtener resultado.
• Sincronización incremental: listar cambios desde un cursor.

Plantilla de flujo:

• Objetivo (qué quiere lograr el consumidor).
• Precondiciones (permisos, estados requeridos).
• Pasos con requests/responses.
• Ramas (qué pasa si X falla).
• Observabilidad (IDs de correlación, logs, métricas).

Paso 5: Documenta casos de error como parte del contrato

En lugar de una lista genérica, documenta errores por operación y por flujo. Para cada error:

• Código de estado y código de error de dominio.
• Mensaje orientado a acción (qué debe hacer el cliente).
• Campos adicionales (por ejemplo, field, reason, retryAfter).

{"error":{"code":"orders.invalid_item","message":"El SKU no existe o no está disponible","details":[{"field":"items[0].sku","reason":"unknown_sku"}],"requestId":"req_7c9f..."}}

OpenAPI como estándar de contrato (source of truth)

OpenAPI permite describir la API de forma legible por humanos y herramientas: documentación, SDKs, validación, mocks y pruebas. Trátalo como contrato: si no está en OpenAPI, no existe; si está en OpenAPI, debe cumplirse.

Qué debe incluir tu especificación OpenAPI

• Info y servidores: entornos, base URLs, contacto, términos.
• Seguridad: esquemas (Bearer, OAuth2), scopes por operación.
• Paths: operaciones con operationId estable, tags por dominio.
• Parámetros: path/query/header, tipos, restricciones, ejemplos.
• Request bodies: content, esquemas, ejemplos realistas.
• Responses: códigos de estado, headers, esquemas y ejemplos.
• Modelos reutilizables: components/schemas, components/responses, components/parameters.
• Modelos de error reutilizables: un esquema común y respuestas referenciables.

Ejemplo de patrones recomendados en OpenAPI (fragmentos)

1) Esquemas reutilizables con ejemplos

components:  schemas:    Order:      type: object      required: [id, status, customerId, items, currency, createdAt]      properties:        id: { type: string, example: "ord_10001" }        status: { type: string, enum: [processing, paid, cancelled], example: "processing" }        customerId: { type: string, example: "cus_123" }        items:          type: array          items:            $ref: "#/components/schemas/OrderItem"        currency: { type: string, example: "EUR" }        createdAt: { type: string, format: date-time, example: "2026-01-15T10:12:45Z" }

2) Parámetros y paginación como componentes

components:  parameters:    Cursor:      name: cursor      in: query      required: false      schema: { type: string }      description: "Cursor opaco para paginación."      example: "eyJvZmZzZXQiOjIwMH0="    Limit:      name: limit      in: query      required: false      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }      description: "Tamaño de página."

3) Respuestas y errores reutilizables

components:  schemas:    ApiError:      type: object      required: [error]      properties:        error:          type: object          required: [code, message, requestId]          properties:            code: { type: string, example: "orders.invalid_item" }            message: { type: string, example: "El SKU no existe o no está disponible" }            requestId: { type: string, example: "req_7c9f..." }            details:              type: array              items:                type: object                properties:                  field: { type: string, example: "items[0].sku" }                  reason: { type: string, example: "unknown_sku" }  responses:    BadRequest:      description: "Solicitud inválida"      content:        application/json:          schema: { $ref: "#/components/schemas/ApiError" }

4) Operaciones con códigos de estado y ejemplos alineados

paths:  /v1/orders:    post:      operationId: createOrder      tags: [Orders]      security:        - bearerAuth: []      requestBody:        required: true        content:          application/json:            schema:              $ref: "#/components/schemas/CreateOrderRequest"            examples:              simple:                value: { customerId: "cus_123", items: [{ sku: "SKU-1", qty: 2 }] }      responses:        "201":          description: "Pedido creado"          content:            application/json:              schema: { $ref: "#/components/schemas/Order" }              examples:                created:                  value: { id: "ord_10001", status: "processing", customerId: "cus_123", items: [{ sku: "SKU-1", qty: 2, unitPrice: 19.99 }], currency: "EUR", createdAt: "2026-01-15T10:12:45Z" }        "400": { $ref: "#/components/responses/BadRequest" }        "401": { $ref: "#/components/responses/Unauthorized" }

Pautas de estilo para documentación y contrato

Nombres consistentes y predecibles

• operationId: verbo+recurso en camelCase (createOrder, listOrders), estable en el tiempo.
• Campos: una convención única (por ejemplo, camelCase) y mantenla en toda la API.
• Enums: valores estables, documentados y con significado claro (evita abreviaturas internas).
• Tags: agrupa por dominio funcional (Orders, Customers), no por capa técnica.

Descripciones precisas (orientadas a decisiones)

• Explica cuándo usar una operación y cuándo no.
• Documenta restricciones (rangos, formatos, estados permitidos) donde el consumidor las ve: en el esquema y en texto.
• Indica efectos secundarios (por ejemplo, creación de eventos, cambios de estado).

Ejemplos alineados con la realidad

• Usa valores plausibles (IDs con formato real, fechas ISO, monedas válidas).
• Incluye cabeceras que el cliente realmente debe enviar/leer.
• Muestra ejemplos de error con el mismo formato que producción.
• Evita ejemplos contradictorios con el esquema (tipos, campos requeridos).

Changelog, guía de migración y deprecaciones

Changelog útil para integradores

Un changelog efectivo permite evaluar impacto rápidamente:

• Fecha y versión (o release id).
• Tipo: Added / Changed / Deprecated / Removed / Fixed / Security.
• Impacto: breaking vs no-breaking, y a quién afecta.
• Acción requerida: pasos concretos para el consumidor.
• Referencias: links a endpoints/operaciones OpenAPI afectadas.

## 2026-01-20  - Changed  - createOrder: el campo items[].qty ahora mínimo 1 (antes permitía 0). Impacto: validación 400 para clientes que enviaban 0. Acción: ajustar validación en cliente.  - Added  - Order.status incluye "paid". Impacto: actualizar manejo de enums.

Guía de migración (cuando hay cambios con impacto)

Incluye una guía por escenario, no solo una lista de cambios:

• Quién debe migrar (qué integraciones se ven afectadas).
• Antes vs después con ejemplos completos.
• Checklist de cambios en código, validaciones, mapeos y pruebas.
• Plan de deprecación: fechas, comportamiento durante la transición, cómo detectar uso antiguo.

Pruebas de contrato para evitar divergencia implementación-diseño

Las pruebas de contrato verifican automáticamente que la implementación cumple el contrato OpenAPI y que los consumidores no se rompen con cambios no previstos.

Estrategia práctica (paso a paso)

Paso 1: Valida OpenAPI en CI

• Lint del spec: consistencia, referencias rotas, ejemplos válidos.
• Reglas propias: naming, presencia de operationId, modelos de error obligatorios.

Paso 2: Pruebas del servidor contra el contrato

• Para cada endpoint crítico, ejecuta tests que validen que la respuesta cumple el esquema (tipos, requeridos, enums).
• Valida también errores: que el formato de error coincide con ApiError.

Paso 3: Pruebas del consumidor (consumer-driven contracts) cuando aplique

• Los consumidores publican expectativas (campos usados, escenarios).
• El proveedor verifica que puede satisfacerlas antes de desplegar.

Paso 4: Mocks y entornos de sandbox alineados al contrato

• Genera mocks desde OpenAPI para pruebas tempranas.
• Asegura que sandbox devuelve ejemplos realistas (incluyendo errores) y no “respuestas felices” permanentes.

Checklist de “no divergencia”

• El spec OpenAPI se versiona junto al código.
• Los cambios en endpoints/esquemas requieren actualización de ejemplos.
• Se bloquea el merge si el spec no valida o si los tests de contrato fallan.
• Se publican changelog y migración cuando hay impacto para consumidores.