Diseño de API
Diseña el contrato antes de la implementación.
Cuándo usar
Úsalo cuando el usuario:
- diseña una nueva API o interfaz;
- cambia un contrato existente;
- define esquemas de solicitud/respuesta;
- revisa manejo de errores, autenticación, paginación o versionado;
- se integra con un servicio de terceros;
- pregunta "¿cómo debería verse este endpoint?".
1. Clarificar el contrato
Identifica:
- quién llama a la API: frontend, móvil, servicio, socio, agente;
- qué necesita lograr el llamante;
- qué datos entran y salen;
- qué datos no debe ver nunca el llamante;
- requisitos de latencia, volumen y confiabilidad;
- restricciones de compatibilidad y versionado.
2. Modelar recursos y acciones
- Usa sustantivos para recursos y verbos explícitos para operaciones que no sean CRUD.
- Mantén las URLs estables y predecibles.
- Prefiere una forma clara de hacer una cosa.
- Evita filtrar la estructura de la base de datos en el contrato público.
- Define identificadores, propiedad y tenencia.
3. Definir el esquema
Para cada endpoint o interfaz:
- método y ruta;
- propósito;
- autenticación y permisos;
- parámetros de ruta, consulta y cuerpo;
- reglas de validación;
- respuesta exitosa;
- respuestas de error;
- idempotencia;
- paginación;
- límites de tasa;
- ejemplos.
4. Diseñar errores
Cada error debe incluir:
- un código estable legible por máquina;
- un mensaje legible por humanos;
- el campo o parámetro que lo causó;
- un ID de solicitud para soporte;
- sin trazas de pila, secretos ni rutas internas.
Usa códigos de estado HTTP consistentes. No devuelvas 200 para una operación fallida.
5. Seguridad y privacidad
- Autentica cada endpoint no público.
- Autoriza a nivel de objeto, no solo a nivel de ruta.
- Valida toda entrada en el límite.
- Devuelve solo los campos que necesita el llamante.
- No expongas IDs internos si filtran información.
- Define límites de tasa y controles de abuso.
- Trata los webhooks como entrada no confiable.
6. Evolutividad
- Agrega campos en lugar de cambiar su significado.
- Mantén los campos antiguos hasta que los clientes migren.
- Versiona solo cuando sea necesario.
- Documenta la obsolescencia y la migración.
- Evita cambios disruptivos en versiones menores.
7. Formato de salida
## Contrato
### `MÉTODO /ruta`
**Propósito:** <qué hace>
**Autenticación:** <quién puede llamarlo>
**Idempotencia:** <sí/no y clave>
#### Solicitud
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
#### Respuesta
```json
{}
```
#### Errores
| Estado | Código | Cuándo |
|---|---|---|
#### Ejemplo
```http
MÉTODO /ruta
...
```
## Compatibilidad
- <qué puede cambiar>
- <qué requiere una nueva versión>
## Preguntas abiertas
- <pregunta>
Reglas
- No inventes reglas de negocio.
- No expongas campos internos sin una razón.
- No uses nombres inconsistentes entre endpoints.
- No diseñes una API pública basada en el esquema actual de la base de datos.
- No omitas el comportamiento de errores y estados vacíos.
- Si la API maneja dinero, salud o datos personales, requiere una revisión de seguridad.
Verificaciones de calidad
- El llamante y la tarea están claros.
- El esquema está completo.
- Los errores son consistentes y seguros.
- La autenticación y los permisos a nivel de objeto están definidos.
- La paginación y los límites están definidos.
- Se aborda la compatibilidad.
- Los ejemplos son válidos.