Principios de REST: recursos, métodos HTTP, códigos de respuesta

Empecemos con el manifiesto de las REST API: los recursos son el alfa y el omega, la esencia de todo REST. ¿Recuerdas que comentamos que las REST API trabajan con objetos y no con acciones? En REST cualquier objeto con el que interactúa tu servidor se llama recurso. Tu tarea es "direccionar" correctamente ese recurso para que el cliente pueda encontrarlo. Aquí entra en escena el URI.

URI (Uniform Resource Identifier) — es la dirección única de un recurso en tu servidor. Simplifiquémoslo: si tu servidor es un gran almacén, el URI es la ubicación del estante donde está la caja que buscas (tu recurso).

Ejemplo de un URI simple:

https://api.example.com/users

¿Cómo diseñar correctamente los URI?

Pongamos las cosas claras: el URI no es algo "para llevar". Es como el escaparate de tu tienda — debe ser atractivo y dejar claro al posible comprador qué vendes aquí.

Unos cuantos consejos:

1. Usa sustantivos, no verbos.
   • Correcto: /users, /products/{productId}/reviews.
   • Incorrecto: /getUsers, /deleteProduct.
2. Usa plural para colecciones de recursos.
   • Por ejemplo, /users para referirse a todos los usuarios.
3. Usa jerarquía para recursos anidados.
   • Por ejemplo, para obtener las órdenes de un usuario concreto: /users/{userId}/orders.
4. Los URI no son verbos ni acciones. Eso lo defines con los métodos HTTP (luego lo vemos).

Ejemplo:

GET https://api.example.com/users
POST https://api.example.com/users
GET https://api.example.com/users/123

Métodos HTTP: los protagonistas de REST

Los métodos HTTP son los operadores clave para trabajar con recursos en las REST API.

Las REST API son estrictas en su simplicidad. Si quieres añadir un nuevo usuario, usa POST. ¿Quieres borrarlo? Usa DELETE. Y si de repente decides actualizar su teléfono y haces la petición GET /users/updatePhone?id=123, la karma de tu REST API quedará irremediablemente estropeada.

Ejemplo: Gestión de usuarios con métodos HTTP

GET    /users         - Obtener todos los usuarios
POST   /users         - Crear un nuevo usuario
GET    /users/123     - Obtener un usuario concreto
PUT    /users/123     - Actualizar completamente al usuario 123
PATCH  /users/123     - Actualizar solo parte de los datos del usuario 123
DELETE /users/123     - Eliminar al usuario 123

Si la API fuera una app móvil, los métodos HTTP serían los botones "Agregar", "Eliminar", "Actualizar".

Códigos de respuesta HTTP: tus aliados en el debug

Cuando el servidor recibe una petición, debe comunicar al cliente el resultado de la operación. Para eso existen los códigos de respuesta HTTP. Se dividen en grupos, sin "gemelos".

Principales códigos que necesitas conocer

2xx: códigos exitosos

• 200 OK: todo fue bien. El servidor devolvió los datos.
• 201 Created: tu recurso fue creado con éxito.
• 204 No Content: la solicitud se procesó, pero no hay nada que devolver.

4xx: errores del cliente

• 400 Bad Request: algo está mal con la solicitud (por ejemplo, JSON inválido).
• 401 Unauthorized: no estás autorizado.
• 403 Forbidden: no tienes permisos.
• 404 Not Found: recurso no encontrado.

5xx: errores del servidor

• 500 Internal Server Error: código genérico para un problema en el servidor.
• 503 Service Unavailable: "lo siento, me fui a comer. Intenta de nuevo más tarde."

Ejemplo de uso de códigos

Imagina que tienes una API para gestionar libros:

GET /books/{bookId}

1. Si el libro se encuentra, el servidor devolverá 200 OK y los datos del libro.
2. Si no se encuentra el libro, recibirás 404 Not Found.
3. Si tu servidor decide "dispararse en un pie", hay alta probabilidad de recibir 500 Internal Server Error.

Resumen

Hoy hemos repasado tres principios básicos de REST:

1. Recursos y su representación mediante URI.
2. Métodos HTTP que permiten interactuar con los recursos.
3. Códigos de respuesta HTTP que hacen tu API más amigable para el cliente.

Ahora estás listo para pasar a crear tus primeros controladores REST API. Y nunca llames a una API "simple" hasta que no la hayas probado tú mismo con cosas como Postman. Las REST API son simples hasta que recibes una petición de un cliente con el parámetro foo=bar&baz=<injected_script>.

En la próxima clase empezaremos a implementar controladores REST API. Prepárate para anotaciones, JSON y las preguntas infinitas de "¿por qué me sale un 404?". ¡Hasta la próxima!