Desarrollador Full-stack: pregunta de entrevista
¿Cómo diseñas una API clara?
Una API clara modela recursos y operaciones del dominio de forma consistente, valida entradas, usa estados y errores previsibles, soporta paginación e idempotencia y evoluciona con una política de compatibilidad.
Respuesta directa
Qué debe cubrir una buena respuesta
Cómo funciona
Una API clara es predecible: los recursos son sustantivos con nombres coherentes, las operaciones se corresponden con métodos HTTP y su semántica estándar, y el mismo cuerpo de error aparece en todas partes con un código legible por máquina y un mensaje humano. Las entradas se validan en el borde con respuestas 4xx precisas. Las listas paginan con cursores, los filtros y el orden son parámetros explícitos, las escrituras que los clientes reintentan aceptan claves de idempotencia y las marcas de tiempo usan un formato en UTC. El contrato se escribe en OpenAPI antes que el código, lo revisa un consumidor y evoluciona bajo una política de compatibilidad declarada.
Ejemplo
GET /orders?status=open&cursor=abc devuelve una página de pedidos y el siguiente cursor; POST /orders con una cabecera Idempotency-Key crea uno y devuelve 201 con cabecera Location; un fallo de validación devuelve 422 con una lista de errores por campo, y cada error lleva el mismo sobre con code, message y request_id para que el frontend lo pinte de forma uniforme.
Errores frecuentes
- Usar POST para todo y codificar la acción en el cuerpo.
- Devolver 200 con un objeto de error dentro del payload.
- Exponer nombres de columnas e IDs internos directamente como contrato público.
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.
Abre el espacio de trabajo de escritorio y ensaya una respuesta clara con tus propias palabras.