Una API REST bien diseñada es intuitiva, consistente y fácil de mantener. Estas prácticas aplican a cualquier lenguaje y framework.

Nombres de recursos

Sustantivos en plural: /users, /articles. Jerarquía: /users/123/posts. URLs limpias, sin verbos. Versionado: /v1/users.

Métodos HTTP

GET (leer), POST (crear), PUT (reemplazar), PATCH (actualizar parcial), DELETE (eliminar). Siempre respeta la semántica HTTP.

Respuestas consistentes

Estructura JSON unificada. Códigos HTTP correctos: 200, 201, 204, 400, 401, 403, 404, 409, 422, 500. Mensajes de error descriptivos.

Paginación y filtros

?page=1&limit=20, ?offset=0&limit=20. Cursor-based para grandes datasets. Filtros: ?status=active&q=búsqueda. Sorting: ?sort=-created_at.