API Design

Diseño de APIs y Endpoints

Cuándo usar: al crear o modificar endpoints, diseñar el contrato de un servicio, definir el formato de errores, decidir versionado, paginación o idempotencia, revisar una API antes de exponerla, o al elegir entre REST/GraphQL/gRPC/webhooks. Si estás escribiendo una ruta, un DTO o un código de estado, esta guía aplica.

Una API es un contrato público: una vez que un cliente depende de ella, cambiarla cuesta caro. Diseña pensando en que vas a vivir con esa decisión durante años. La consistencia vale más que la perfección: es mejor una convención "buena" aplicada en todos lados que una convención "perfecta" aplicada a medias.

1. Principios fundamentales

1. El contrato es lo primero (contract-first). Diseña el request/response y los errores antes de escribir lógica. El contrato es la única parte que no puedes romper sin avisar.
2. Orientación a recursos, no a acciones. La URL identifica cosas (recursos); el verbo HTTP identifica la acción. POST /users en vez de POST /createUser.
3. Predecible y consistente. Si GET /users devuelve una lista paginada, GET /orders debe hacerlo igual. Un desarrollador debe poder adivinar tu API tras ver tres endpoints.
4. Explícito sobre implícito. Estados, errores y formatos declarados. Nada de "si el campo viene vacío significa X".
5. Robusto en lo que aceptas, estricto en lo que prometes. Valida entrada con firmeza; mantén tu salida estable y documentada.
6. Diseña para el fallo. Reintentos, timeouts, idempotencia y rate limiting no son extras: son parte del contrato.
7. Seguridad y privacidad por defecto. No expongas internals, IDs autoincrementales sensibles ni detalles de stack. Ver skill security.
8. La documentación es parte del entregable. Una API sin OpenAPI actualizado es una API rota a medias.

2. Reglas de oro (Haz / Evita)

3. Diseño orientado a recursos y nomenclatura de URLs

Un recurso es un sustantivo del dominio: user, order, invoice. La URL es su dirección.

Reglas de nomenclatura:

• Sustantivos, no verbos. El verbo lo pone HTTP.
• Plural para colecciones: /users (colección), /users/123 (elemento). Mantén el plural incluso para el elemento; no mezcles /user/123.
• Jerarquía para relaciones de pertenencia: /users/123/orders/456. Evita anidar más de 2 niveles; a partir de ahí usa filtros: /orders?userId=123.
• minúsculas siempre en el path.
• kebab-case para segmentos de varias palabras: /purchase-orders, no /purchaseOrders ni /purchase_orders.
• Sin extensiones (.json) ni sufijos de tecnología. La negociación de formato va en Accept.
• IDs opacos si es posible (UUID o ULID) para no filtrar volumen ni permitir enumeración. Ver security.
• Sub-recursos para acciones que no encajan en CRUD, modeladas como recurso: POST /orders/456/cancellations en lugar de POST /orders/456/cancel. Cuando es imposible, un endpoint de "acción" acotado es tolerable: POST /orders/456/actions/cancel.

GET    /articles                 # lista de artículos
POST   /articles                 # crea un artículo
GET    /articles/{id}            # un artículo
PATCH  /articles/{id}            # modifica parcialmente
DELETE /articles/{id}            # elimina
GET    /articles/{id}/comments   # comentarios de ese artículo

4. Verbos HTTP: semántica, seguridad e idempotencia

• Seguro = no altera estado del servidor (solo lectura). Nunca uses GET para mutar; los proxies y prefetchers pueden repetirlo.
• Idempotente = repetir la misma petición N veces deja el mismo estado final que hacerla 1 vez. Clave para reintentos seguros ante timeouts de red.
• PUT vs PATCH: PUT reemplaza el recurso entero (los campos omitidos se borran/resetean); PATCH toca solo lo enviado. No uses PUT para updates parciales.
• * PATCH puede ser idempotente según cómo lo diseñes. Un PATCH que fija valores absolutos ({"status": "paid"}) es idempotente; uno que hace deltas ({"balance": "+10"}) no lo es. Prefiere el primero.
• POST es el verbo por defecto para acciones no idempotentes; protégelo con Idempotency-Key (sección 8).

5. Códigos de estado HTTP

Usa el código que comunica el resultado real. El status es la primera señal que lee el cliente y su lógica de reintento depende de él.

Claves:

• Distingue 401 vs 403: 401 = "no sé quién eres"; 403 = "sé quién eres y no puedes".
• Distingue 400 vs 422: 400 = no pude parsear; 422 = parseé pero los datos violan reglas. Muchos frameworks usan 400 para ambos; si eliges 422 para validación, sé consistente.
• 4xx = culpa del cliente (no reintentar igual); 5xx = culpa del servidor (reintentable con backoff). Esta división guía la lógica de reintentos del cliente.
• Nunca 200 con un error dentro. Rompe caches, monitoreo y clientes.

6. Formato de errores consistente (RFC 7807)

Todos los errores deben tener la misma forma en toda la API. Usa application/problem+json (RFC 9457, antes RFC 7807).

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/validation",
  "title": "La solicitud contiene campos inválidos",
  "status": 422,
  "detail": "El campo 'email' no tiene un formato válido.",
  "instance": "/users",
  "traceId": "b7d3f1a2-...",
  "errors": [
    { "field": "email", "code": "invalid_format", "message": "Debe ser un email válido." },
    { "field": "age",   "code": "out_of_range",  "message": "Debe ser mayor o igual a 18." }
  ]
}

Campos:

• type (URI): identificador estable y documentable del tipo de error. La clave que el cliente puede usar para ramificar lógica.
• title: resumen legible, constante por type.
• status: repite el código HTTP (útil cuando el status se pierde en logs).
• detail: mensaje específico de esta ocurrencia.
• instance: URI de la ocurrencia.
• traceId (extensión): correlaciona con logs/observabilidad. Ver skill error-handling-observability.
• errors[] (extensión): detalle por campo para validación. Usa code legible por máquina, no solo message.

Reglas:

• Nunca filtres stack traces, nombres de tablas, queries SQL ni rutas internas en detail. Ver security.
• Mensajes accionables para el cliente, genéricos para lo interno (loguea lo detallado del lado servidor con el mismo traceId).
• El code por campo permite i18n y ramificación programática sin parsear texto.

7. Versionado de API

Versiona desde el primer release. No versionar es apostar a que nunca cambiarás nada incompatible.

Recomendación: versionado en URL path (/v1) para la mayoría de APIs públicas y de producto: es explícito, trivial de rutear, cachear y depurar. Reserva versionado por header/media-type para APIs muy grandes con ciclos de vida por recurso.

Reglas de evolución:

• Cambios aditivos son compatibles: agregar campos opcionales o endpoints no rompe. Los clientes deben ignorar campos desconocidos (diséñalos tolerantes).
• Cambios incompatibles (renombrar/eliminar campos, cambiar tipos, endurecer validación) exigen nueva versión mayor.
• Publica política de deprecación: header Deprecation + Sunset (RFC 8594), fecha de retiro y guía de migración. Da meses, no días.
• Fechas como versión (2026-06-30) funcionan bien para APIs con evolución continua (estilo Stripe).

8. Paginación, filtrado, ordenamiento y búsqueda

Nunca devuelvas una colección sin límite. Pagina siempre.

Offset/limit — simple, permite saltar a página N:

GET /users?limit=20&offset=40

• Pros: fácil, "página 5" directo.
• Contras: se degrada en datasets grandes (el motor cuenta y descarta filas); inconsistente si se insertan/borran filas mientras paginas (saltos o duplicados).

Cursor (keyset) — recomendado para listas grandes o en tiempo real:

GET /users?limit=20&cursor=eyJpZCI6MTIzfQ==

{
  "data": [ /* ... */ ],
  "pagination": {
    "nextCursor": "eyJpZCI6MTQzfQ==",
    "hasMore": true
  }
}

• Pros: rendimiento estable (usa índice WHERE id > ?), consistente ante inserciones. Ver database-design y performance.
• Contras: no permite "ir a la página 7"; solo siguiente/anterior. El cursor debe ser opaco (codifica el keyset, no lo expongas crudo).

Filtrado, orden y búsqueda por query params, con convención estable:

GET /orders?status=paid&createdAfter=2026-01-01&sort=-createdAt,total&q=laptop&fields=id,total

• Filtros: campo=valor. Para rangos, prefijos claros: createdAfter, minPrice.
• Orden: sort=-createdAt (- = descendente); múltiples separados por coma.
• Búsqueda de texto libre: q=.
• Selección de campos (sparse fieldsets): fields=id,name para reducir payload.
• Documenta y valida los campos permitidos: no permitas ordenar/filtrar por columnas arbitrarias (riesgo de rendimiento e inyección). Ver security.

9. Idempotencia y reintentos seguros

Las redes fallan después de que el servidor procesó pero antes de que la respuesta llegue. El cliente reintenta y —sin protección— duplica la operación (doble cobro, doble pedido).

• GET, PUT, DELETE son idempotentes por naturaleza: reintentar es seguro.
• POST no lo es. Protégelo con Idempotency-Key:

POST /payments
Idempotency-Key: 8f14e45f-...
Content-Type: application/json

Mecánica del lado servidor:

1. El cliente genera una clave única (UUID) por intento lógico de operación y la reutiliza en cada reintento.
2. El servidor almacena (idempotency-key → resultado) con TTL (p. ej. 24h).
3. Si llega una clave ya vista: devuelve el resultado guardado sin re-ejecutar.
4. Si la clave está en proceso: responde 409 Conflict o espera.
5. Valida que el body coincida con el de la primera vez; si difiere, 422.

Reglas:

• El cliente reintenta con backoff exponencial + jitter, solo ante 5xx, 429 y timeouts de red. Nunca reintenta 4xx (salvo 429).
• Operaciones intrínsecamente no idempotentes (crear pago, enviar email) requieren Idempotency-Key.
• Persiste las claves en almacenamiento durable (no solo memoria) para sobrevivir reinicios. Ver database-design.

10. Validación de entrada y contratos (schema-first)

• Schema-first / OpenAPI-first: define el contrato en OpenAPI y genera validadores, tipos y stubs desde ahí. El schema es la fuente de verdad, no el código.
• Valida todo lo que entra en el borde: tipos, formatos, rangos, longitudes, enums, campos requeridos. Rechaza lo desconocido según política (estricto para writes sensibles).
• DTOs separados de entidades de dominio. No serialices tu modelo de base de datos directo: filtras internals y acoplas el contrato al esquema de datos. Define CreateUserRequest, UserResponse explícitos.
• No confíes en el cliente para nada de seguridad: precios, roles, ownerId se derivan del servidor/token, nunca del body.
• Devuelve 422 con la lista de campos inválidos (sección 6), no un 500.

// CreateUserRequest (lo que aceptas)
{ "email": "a@b.com", "password": "secret", "name": "Ada" }

// UserResponse (lo que devuelves — sin password, sin campos internos)
{ "id": "usr_01H...", "email": "a@b.com", "name": "Ada", "createdAt": "2026-06-30T10:00:00Z" }

11. Autenticación y autorización

• Autenticación = quién eres. Autorización = qué puedes hacer. Son distintas; implementa ambas.

Reglas:

• Credenciales siempre por header Authorization: Bearer <token>, nunca en query string (se filtran en logs y caches).
• Solo HTTPS. Sin TLS, cualquier token viaja en claro.
• Nunca devuelvas datos sensibles (password hash, tokens internos, PII innecesaria) en respuestas. Usa DTOs.
• Autorización por recurso: verifica que el usuario es dueño de /orders/456, no solo que está autenticado. El fallo aquí es una de las vulnerabilidades más comunes (BOLA/IDOR).
• 401 para auth ausente/inválida; 403 para permiso denegado. Para no revelar existencia de recursos ajenos, 404 puede ser preferible a 403.
• Detalle profundo en la skill security.

12. Rate limiting

Protege la API de abuso y garantiza equidad. Comunica los límites por headers:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 30

• 429 cuando se excede la cuota.
• Retry-After: segundos (o fecha HTTP) que el cliente debe esperar. El cliente debe respetarlo.
• Expón el estado de cuota en cada respuesta (RateLimit-*) para que el cliente se autorregule antes de chocar.
• Define límites por clave/usuario/IP y por endpoint (los caros más estrictos). Ver performance y security.

13. Caché HTTP

Reduce latencia y carga sin lógica extra en el cliente. Ver performance.

• Cache-Control controla la cacheabilidad:
  • public, max-age=3600 — cacheable por proxies y navegador 1h.
  • private, max-age=0, no-cache — solo cliente, revalida siempre.
  • no-store — datos sensibles, nunca se guardan.
• ETag (validador de versión) + petición condicional:

# Respuesta
ETag: "a1b2c3"

# Petición posterior del cliente
GET /articles/1
If-None-Match: "a1b2c3"
# → 304 Not Modified si no cambió (ahorra ancho de banda)

• ETag + If-Match también sirve para concurrencia optimista: PUT/PATCH con If-Match: "a1b2c3" → 412 Precondition Failed si otro modificó el recurso. Evita el "last write wins".
• Last-Modified + If-Modified-Since es la alternativa basada en fecha.

14. HATEOAS y madurez de Richardson (breve)

El Modelo de Madurez de Richardson clasifica cuán RESTful es una API:

• Nivel 0 — un solo endpoint, todo por POST (RPC sobre HTTP). No REST.
• Nivel 1 — Recursos: múltiples URLs por recurso, pero un solo verbo.
• Nivel 2 — Verbos HTTP: verbos y códigos de estado correctos. Aquí vive la mayoría de las APIs "REST" reales y es un objetivo perfectamente válido.
• Nivel 3 — HATEOAS: las respuestas incluyen links que indican las acciones siguientes posibles.

{
  "id": "ord_123",
  "status": "pending",
  "_links": {
    "self":   { "href": "/orders/ord_123" },
    "cancel": { "href": "/orders/ord_123/cancellations", "method": "POST" },
    "pay":    { "href": "/orders/ord_123/payments", "method": "POST" }
  }
}

Pragmatismo: apunta a Nivel 2 como mínimo sólido. HATEOAS (Nivel 3) es elegante pero pocos clientes lo aprovechan; adóptalo solo si tu consumidor navegará dinámicamente. No te obsesiones con la pureza.

15. REST vs GraphQL vs gRPC vs Webhooks

Claves:

• REST es el default seguro para APIs de producto y públicas.
• GraphQL brilla con front-ends que consumen datos heterogéneos; su costo es caché, rate limiting por complejidad de query y evitar N+1 (ver performance, database-design).
• gRPC para el interior de tu sistema (service-to-service).
• Webhooks complementan REST para lo asíncrono; firma el payload (HMAC) y hazlos idempotentes del lado receptor (reintentos duplican). Ver security.

16. Consistencia: naming, fechas, casing, envelopes

• Casing de campos: elige uno y aplícalo en TODA la API. snake_case es común en REST; camelCase si tu ecosistema es JS/JSON. Nunca los mezcles.
• Fechas y horas: siempre ISO 8601 en UTC con offset: 2026-06-30T10:00:00Z. Nunca formatos locales ambiguos ni timestamps epoch sin documentar. Incluye zona.
• Booleanos con nombres claros: isActive, hasShipped (no flag, no status=1).
• Enums como strings estables ("pending", "paid"), no números mágicos. Documenta los valores posibles.
• Dinero: entero en la unidad mínima (centavos) + código de moneda ISO 4217 ({ "amount": 1050, "currency": "USD" }), o string decimal. Nunca float para dinero.
• Envelope de respuesta: decide si envuelves o no y sé consistente:

  { "data": { ... }, "meta": { ... } }        // colección o recurso
  { "data": [ ... ], "pagination": { ... } }  // lista
  

  Un envelope da lugar para metadata/paginación/links sin romper el contrato. Alternativa válida: recurso "desnudo" + paginación en headers. Elige una.
• Null vs ausente: define la semántica. Omitir un campo ≠ enviarlo null. Documenta cuál usas (relevante para PATCH).

17. Seguridad de API (esenciales)

Complementa con la skill security; aquí lo mínimo innegociable:

• HTTPS obligatorio. Redirige HTTP→HTTPS; considera HSTS.
• Valida y sanitiza toda entrada. Trata cada input como hostil: previene inyección SQL/NoSQL/comando (ver database-design).
• No filtres internals en errores: ni stack traces, ni nombres de tabla, ni versiones de software. Mensaje genérico al cliente, detalle en logs con traceId.
• CORS restrictivo: whitelist explícita de orígenes; no uses Access-Control-Allow-Origin: * en endpoints autenticados.
• Rate limiting contra fuerza bruta y abuso (sección 12).
• Autorización por objeto (evita IDOR/BOLA): verifica ownership en cada acceso, no solo autenticación.
• Mínima exposición de datos: devuelve solo lo necesario; nada de PII o secretos de más.
• Payloads con límite de tamaño y timeouts, para frenar DoS.
• Secretos fuera del código y de las URLs. Tokens por header, nunca en query params.

18. Documentación como contrato (OpenAPI)

• OpenAPI (Swagger) es el contrato ejecutable: describe endpoints, schemas, ejemplos, errores y auth. Genera docs, SDKs, mocks y tests desde él.
• Contract-first: escribe/actualiza el OpenAPI antes de implementar. Que el código cumpla el spec, no al revés.
• Versiona el contrato junto al código (en el repo) y trátalo como parte de la definición de "hecho": un PR que cambia la API sin actualizar OpenAPI está incompleto.
• Valida en CI que la implementación cumple el spec (contract testing). Detecta breaking changes automáticamente comparando versiones del spec.
• Publica ejemplos reales de request/response por endpoint, incluidos los errores.

Anti-patrones comunes

• Verbos en la URL: /getUser, /createOrder, /user/delete. Usa recursos + verbo HTTP.
• Túnel POST: todo por POST con un campo action (Richardson Nivel 0).
• 200 OK con error dentro del body. Rompe clientes, caché y monitoreo.
• Filtrar internals en errores (stack trace, SQL, rutas). Fuga de seguridad.
• No paginar y devolver colecciones ilimitadas. Bomba de latencia/memoria.
• Naming/casing inconsistente entre endpoints (user_id vs userId).
• No versionar y luego romper a todos los clientes con un cambio incompatible.
• Serializar la entidad de dominio/DB directo, exponiendo campos internos y acoplando el contrato al esquema.
• POST de cobro sin idempotencia: el reintento por timeout cobra dos veces.
• Confiar en el cliente para precio, rol u ownership (viene en el body).
• Ignorar códigos de estado: todo 200 o todo 500.
• Anidamiento profundo de rutas (/a/1/b/2/c/3/d/4): usa filtros.
• Fechas locales/ambiguas sin zona horaria.
• Breaking changes silenciosos en producción sin Deprecation/Sunset.

Checklist antes de dar por buena una API

• URLs orientadas a recursos: sustantivos, plural, minúsculas, kebab-case.
• Verbos HTTP con semántica correcta; sin verbos en la ruta.
• Códigos de estado precisos por caso (201 al crear, 422 en validación, 404/403 diferenciados).
• Formato de error único (problem+json) con type, title, status, detail, traceId.
• Sin fugas de internals en errores; mensajes genéricos + logs correlacionados.
• Versionado definido y visible (/v1) con política de deprecación.
• Toda colección paginada (cursor para grandes); filtros/orden validados y documentados.
• Idempotency-Key en POST no idempotentes; reintentos con backoff definidos.
• Entrada validada en el borde; DTOs de request/response separados del dominio.
• AuthN y AuthZ implementadas; autorización por objeto (sin IDOR); solo HTTPS.
• Rate limiting con 429 + Retry-After y headers RateLimit-*.
• Caché donde aplique: ETag/Cache-Control; concurrencia optimista con If-Match.
• Naming, casing, fechas ISO 8601 UTC y formato de dinero consistentes en toda la API.
• Envelope de respuesta y semántica de null/ausencia definidas y uniformes.
• OpenAPI actualizado, versionado en el repo y validado en CI.
• Ejemplos de request/response y de errores documentados por endpoint.

Referencias

• RFC 9457 — Problem Details for HTTP APIs (reemplaza RFC 7807): https://www.rfc-editor.org/rfc/rfc9457
• RFC 9110 — HTTP Semantics (métodos y códigos de estado): https://www.rfc-editor.org/rfc/rfc9110
• RFC 8594 — Sunset HTTP Header: https://www.rfc-editor.org/rfc/rfc8594
• MDN — HTTP: https://developer.mozilla.org/es/docs/Web/HTTP
• MDN — Códigos de estado HTTP: https://developer.mozilla.org/es/docs/Web/HTTP/Status
• OpenAPI Specification: https://spec.openapis.org/oas/latest.html
• Richardson Maturity Model (Martin Fowler): https://martinfowler.com/articles/richardsonMaturityModel.html
• Stripe API (referencia de diseño y idempotencia): https://docs.stripe.com/api
• Google API Design Guide: https://cloud.google.com/apis/design
• OWASP API Security Top 10: https://owasp.org/API-Security/

Skills relacionadas: security (auth, CORS, inyección, secretos), database-design (paginación por keyset, N+1, persistencia de idempotencia), error-handling-observability (traceId, logging, correlación) y performance (caché, rate limiting, payloads).