Anatomía de una URL REST
Un endpoint REST se compone de protocolo, host, prefijo de versión, recurso, ID opcional
y query string. Por ejemplo: https://api.example.com/v1/users/42/orders?status=open.
Cada parte tiene una responsabilidad clara y mantenerlas separadas hace que tu API sea
predecible y fácil de documentar.
Versionado
El prefijo /v1 permite romper compatibilidad sin romper a los clientes
existentes. Cuando publiques /v2, los consumidores migran a su ritmo. La
alternativa es versionar por header
(Accept: application/vnd.api+json;version=2), más limpia pero menos visible.
Para APIs públicas, el versionado por path suele ganar en claridad.
Recursos en plural y verbos HTTP
La regla más extendida: nombres de colecciones siempre en plural. /users,
/orders, /invoices. El verbo HTTP decide la acción: GET para
leer, POST para crear, PUT para reemplazar, PATCH para actualizar parcialmente, DELETE
para borrar. Evitá verbos en la URL: /users/create rompe la convención.
Path params vs query params
- Path params identifican un recurso específico:
/users/42,/orders/abc-123. - Query params filtran, ordenan, paginan:
?status=active&page=2. - Body lleva datos para crear/actualizar (POST, PUT, PATCH).
Anidamiento de recursos
Cuando hay relaciones jerárquicas claras: /users/42/orders lista las órdenes
del usuario 42. Mantené el anidamiento a un nivel; /users/42/orders/7/items/3
se vuelve inmanejable. Si la relación es ambigua, usá query params: /orders?user_id=42.
Paginación, filtros y ordenamiento
Tres patrones populares de paginación: offset/limit (?offset=40&limit=20),
page/size (?page=3&size=20) y cursor
(?cursor=abc&limit=20). Cursor escala mejor con datasets grandes. Para
ordenar, usá un parámetro sort con prefijo - para descendente:
?sort=-created_at,name.
Códigos de estado
Devolvé 2xx para éxito (200 OK, 201 Created, 204 No Content), 4xx para errores del cliente
(400, 401, 403, 404, 409, 422) y 5xx para errores del servidor. No reutilices 200 con un
body {"error": ...}; usá el código correcto.
Documentar con OpenAPI
Una vez fijada la convención, documentá con OpenAPI (Swagger). Escribís un YAML con cada endpoint, sus params, respuestas y ejemplos, y herramientas como Swagger UI o Redoc lo renderizan. Postman e Insomnia importan OpenAPI y arman colecciones automáticamente.