# Diseño de contratos de API

Convierte las interacciones que una interfaz debe soportar en un contrato con el que un consumidor puede construir — y no añade ningún campo que nadie haya descrito.

## Entregable

Un documento Markdown, `api-contract.md`, con la estructura fijada en **Salida** más abajo. Toma las interfaces nombradas en la sección 4 de `architecture-specification.md` y es la entrada de la implementación y de las pruebas que se escriben contra ella.

## Entradas obligatorias

- **Las interacciones que la interfaz debe soportar** — qué necesita hacer un consumidor, enunciado como tareas. Una lista de endpoints sacada de un sistema existente describe lo que se construyó, no lo que hace falta.
- **Los consumidores** — quién o qué llamará a la interfaz y qué le está permitido ver y cambiar a cada uno.

Si falta cualquiera de las dos, detente y repórtalo. Un contrato escrito sin sus consumidores es un esquema, y un esquema no se acuerda con nadie.

## Entradas opcionales

- El modelo de datos que la interfaz expone y las restricciones que ya se aplican sobre él
- El esquema de autenticación y autorización que usan los sistemas del entorno
- Contratos existentes en el mismo sistema y las convenciones que siguen
- Los patrones de llamada esperados: qué operaciones se llaman juntas y cuáles se repiten
- La taxonomía de errores que los consumidores ya manejan
- Restricciones de transporte, codificación o protocolo declaradas por quien lo solicita

Cuando no se aportó una convención, el contrato declara la elección que hizo y la registra como decisión a confirmar, nunca como un estilo de la casa que dio por supuesto. Cuando no se aportó un límite o una cota, se escribe la regla y el valor queda como `desconocido`.

## Ejecución

**1 — Listar las interacciones, no los endpoints.** Una línea por cada cosa que un consumidor necesita hacer, en sus palabras y con su nombre al lado. Los endpoints se derivan de esta lista. Una lista derivada de endpoints reproduce lo que ya existe, incluidos sus errores.

**2 — Nombrar los recursos y sus operaciones.** Agrupa las interacciones en las cosas que la interfaz expone y luego en las operaciones sobre cada una. Una operación que no pertenece a ningún recurso significa que falta un recurso: nombra el que falta en lugar de colgarla del recurso más cercano que la admita.

**3 — Especificar peticiones y respuestas campo a campo.** Por cada campo: nombre, tipo, obligatorio u opcional, qué significa y qué lo restringe. Un campo que quien lo solicita no describió no se añade. Un campo que parece necesario pero no se describió se eleva como pregunta, porque la respuesta cambia quién es dueño del dato.

**4 — Escribir el catálogo de errores.** Cada error que un consumidor puede recibir: la condición que lo provoca, si el consumidor puede reintentar y qué se espera que haga. Una operación cuyas condiciones de error no se pueden listar todavía no se entiende; regístralo así en lugar de entregar un único fallo genérico.

**5 — Fijar autenticación y autorización por operación.** Por cada operación: qué debe demostrar quien llama, qué derecho se exige y qué ocurre cuando ese derecho no está. Una operación sin regla declarada se registra como `autorización desconocida — necesaria antes de implementar`. Nunca se asume abierta ni se asume cerrada.

**6 — Definir las reglas de comportamiento.** Idempotencia por operación: si es segura de repetir, o qué debe aportar quien llama para que lo sea. Paginación: cómo se pide una página, qué la acota y qué ocurre si el conjunto cambia a mitad del recorrido. Orden, concurrencia y límites de uso se escriben solo donde quien lo solicita los declaró.

**7 — Fijar versionado y retirada.** Qué cuenta como cambio incompatible en este contrato, cómo se señala, cómo se entera un consumidor de que una versión termina y durante cuánto tiempo se mantiene una versión. Si no se aportó el periodo de soporte, escribe `desconocido` y nombra a quién debe fijarlo.

## Salida

`api-contract.md`, en este orden:

- **1. Entrada y fecha** — a qué interacciones y a qué consumidores sirve este contrato, quién los aportó y cuándo
- **2. Consumidores** — por consumidor: para qué llama a la interfaz y qué le está permitido ver y cambiar
- **3. Recursos y operaciones** — por recurso: qué representa, sus operaciones y la interacción a la que sirve cada una
- **4. Esquemas de petición y respuesta** — por operación: cada campo con su nombre, tipo, opcionalidad, significado y restricción
- **5. Catálogo de errores** — por error: la condición que lo provoca, si admite reintento y qué debe hacer el consumidor
- **6. Autenticación y autorización** — por operación: qué hay que demostrar, qué derecho se exige y qué ocurre sin él
- **7. Reglas de comportamiento** — idempotencia, paginación, orden, concurrencia y límites de uso allí donde se declararon
- **8. Versionado y retirada** — qué cuenta como cambio incompatible, cómo se señala y cómo termina una versión
- **9. Preguntas abiertas** — la pregunta, qué bloquea, quién puede responderla

## Validación

El contrato está listo cuando se cumple todo esto:

- Cada interacción de la entrada llega exactamente a una operación de la sección 3
- Cada campo de la sección 4 lleva un tipo y declara si es obligatorio
- Cada error de la sección 5 nombra la condición que lo provoca y si se permite reintentar
- Cada operación de la sección 6 declara una regla o lleva la marca `autorización desconocida`
- No aparece ningún límite, cota o periodo de soporte que quien lo solicita no haya aportado
- La sección 9 no está vacía, o declara explícitamente que no queda nada pendiente

Falla la ejecución si aparece un campo que ninguna entrada describió, o si se publica una operación sin regla de autorización y sin la marca `desconocida`.

## Gestión de fallos

- **No hay interacciones** — detente. Informa de que no hay nada que contratar y de que una interfaz diseñada solo desde un modelo de datos sirve al almacén, no a quien llama.
- **No se nombran consumidores** — produce las secciones 1 y 3 a 9, marca la sección 2 como `CONSUMIDORES DESCONOCIDOS` y declara que la sección 6 no se puede cerrar hasta que alguien nombre quién llama a esto.
- **Solo hay una implementación existente** — describe lo que hace la implementación, marca el documento entero como `TAL COMO ESTÁ` y lista en la sección 9 cada comportamiento que parece deliberado pero no está confirmado. Una descripción de lo construido no es un contrato acordado.
- **Los consumidores quieren comportamientos contradictorios** — registra las dos posturas, nombra a ambos consumidores y eleva el conflicto a la sección 9 como bloqueante. No los satisfagas a los dos volviendo opcional la diferencia.
- **Material parcial** — especifica las operaciones que el material sostenga, marca el resto como `INCOMPLETO — pendiente de <pregunta>` y entrega.