Hoy · Hoja de ruta
- 1. Aprende: Qué significa REST, y qué distingue una API bien diseñada de un conjunto de rutas.
- 2. Haz: Analiza dos APIs reales y detecta sus decisiones de diseño.
- 3. Comprueba: Distingues una ruta orientada al recurso de una orientada a la pantalla.
Antes de empezar · 5 minutos, sin apuntes
- Escribe las rutas que tiene hoy tu servidor. ¿Se parecen entre sí?
- Si mañana alguien más las usara, ¿podría adivinar la siguiente?
- ¿Qué información necesitaría para usarlas sin preguntarte?
Recursos, no acciones
Recurso
Una cosa del problema que se puede identificar con una URL: un producto, una categoría, un pedido. La ruta nombra el recurso; el método dice qué se hace con él.
| Con acciones en la ruta | Orientado a recursos |
|---|---|
GET /obtenerProductos |
GET /api/productos |
GET /verProducto?id=7 |
GET /api/productos/7 |
POST /crearProducto |
POST /api/productos |
POST /borrarProducto |
DELETE /api/productos/7 |
La columna derecha tiene una propiedad que la izquierda no: es predecible. Quien conozca dos rutas sabe escribir la tercera.
Los principios que vamos a aplicar
- Las cosas se identifican con URLs
- El método dice la operación
- El código de estado dice el resultado
- Cada petición se entiende sola, sin estado guardado entre ellas
- La representación es JSON, con una forma constante
Sin estado
El servidor no recuerda nada entre una petición y la siguiente. Todo lo necesario viaja en la petición. Es lo que permite que dos copias del servidor atiendan al mismo cliente sin coordinarse, y es la razón de que la autenticación se resuelva con algo que se envía en cada llamada.
Nombrar bien
| Regla | Ejemplo |
|---|---|
| Sustantivos en plural | /api/productos, no /api/producto |
| Minúsculas y guiones | /api/categorias-destacadas |
| Jerarquía para lo que pertenece | /api/categorias/teclados/productos |
| Filtros en la consulta | /api/productos?categoria=teclados&max=100 |
| Sin verbos | El verbo ya es el método |
Filtrar no es una ruta nueva
Los productos baratos no son un recurso distinto de los productos: son los mismos, filtrados. Van en la cadena de consulta, no en la ruta.
La prueba: si al añadir un filtro nuevo tienes que crear una ruta nueva, acabarás con quince rutas que devuelven lo mismo con distinta condición.
Tarea 1 · Analizar y diseñar
- Explora dos APIs públicas y anota diez rutas de cada una.
- Clasifícalas: ¿orientadas a recursos o a acciones?
- Localiza cómo filtran, cómo paginan y cómo devuelven los errores.
- Diseña sobre papel la tabla de rutas de tu proyecto: método, ruta, qué hace, qué devuelve y con qué código.
- Enséñasela a un compañero y comprueba si puede adivinar una ruta que no le has enseñado.
Checkpoint · fin de la sesión 1
- Distingues una ruta orientada al recurso de una orientada a la acción.
- Sabes dónde van los filtros.
- Explicas qué significa que una API no guarde estado.
- Tienes la tabla de rutas de tu proyecto.
Antes de cerrar · 2 minutos, sin mirar
- ¿Por qué las rutas no llevan verbos?
- ¿Dónde van los filtros?
- ¿Qué significa que el servidor no guarde estado?
Ver respuestas
1 · Porque el verbo ya lo aporta el método HTTP.
2 · En la cadena de consulta: no son recursos distintos.
3 · Que no recuerda nada entre peticiones: cada una trae todo lo que necesita.