backend-api-design

Backend API design

Cuándo usar

• Crear un endpoint nuevo o cambiar uno existente.
• Diseñar un contrato entre frontend y backend o entre servicios.
• Revisar un PR que toca rutas, payloads o códigos de estado.

Recursos y verbos

Pensá en recursos (sustantivos), no en acciones:

Acción	Verbo	Ruta
Listar	GET	/usuarios
Obtener	GET	/usuarios/{id}
Crear	POST	/usuarios
Reemplazar	PUT	/usuarios/{id}
Modificar parcial	PATCH	/usuarios/{id}
Borrar	DELETE	/usuarios/{id}
Sub-recurso	GET	/usuarios/{id}/sesiones

Acciones que no son CRUD: POST /usuarios/{id}/activar. No POST /activarUsuario.

Códigos de estado

Los más usados, sin inventar:

• 200 OK — éxito con cuerpo.
• 201 Created — creado, devolvé Location con la URL.
• 204 No Content — éxito sin cuerpo (típico DELETE).
• 400 Bad Request — payload o parámetro inválido.
• 401 Unauthorized — falta credencial o es inválida.
• 403 Forbidden — autenticado, pero no autorizado.
• 404 Not Found — el recurso no existe.
• 409 Conflict — conflicto de estado (duplicado, versión).
• 422 Unprocessable — sintaxis ok, semántica no.
• 429 Too Many Requests — rate limit.
• 500 Internal Server Error — bug nuestro.
• 503 Service Unavailable — caído / mantenimiento.

Nunca 200 con { "error": ... }. El estado va en el HTTP.

Errores estructurados

Adoptá un formato único en toda la API. Recomendado: RFC 9457 (Problem Details):

{
  "type": "https://api.tu-app.com/errors/usuario-no-encontrado",
  "title": "Usuario no encontrado",
  "status": 404,
  "detail": "No existe un usuario con id 'abc123'.",
  "instance": "/usuarios/abc123"
}

Incluí campos extras útiles: errors (lista de fallos por campo), traceId. Nunca devuelvas stack traces ni nombres de tablas a un cliente.

Versionado

• En la URL (/v1/usuarios) — simple, cacheable, visible.
• O en el header (Accept: application/vnd.tuapp.v1+json) — para puristas.
• Subí versión solo en cambio incompatible. Agregar campo opcional no rompe.