REST API Design

El REST es un estilo de arquitectura de software que se utiliza para diseñar APIs. REST es un acrónimo de Representational State Transfer, el cual significa Transferencia de Estado Representacional. Y aunque no explique nada su significado, no es un patron muy dificil de comprender.

Visualice a REST como una forma intuitiva de comunicarse, como usted, querido programador sabe. Cuando uno le habla al servidor este manda una respuesta, en REST, visualice mas de que usted le pide al servidor algo, y este le responde con lo que usted le pidió.

Haciendo mas intuitivo REST, recuerde las peticiones que normalmente hace a un servidor, como GET, POST, PUT, DELETE, etc. Estas peticiones son las que se utilizan en REST para comunicarse con el servidor.

Ahora piense, ¿Como le pido una lista de productos al servidor REST?

Quiza si es un programador harto este tentado a hacer algo como: POST /products/obtener-productos/en-stock/empresa/123/fecha/2021-01-01. Quiza pueda incluso parecerle correcto esto ya que quiza esta mas acostumbrado a usar la Arquitectura de Servicios, pero para REST esto es completamente anti-intuitivo.

En REST se utilizan los verbos de HTTP para comunicarse con el servidor, y estos verbos son: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE, CONNECT. Y estos verbos son los que se utilizan para comunicarse con el servidor.

Por lo tanto, para pedir una lista de productos al servidor, usted debería hacer algo como: GET /products. Y si quisiera obtener un producto en especifico, debería hacer algo como: GET /products/123. Siendo asi muchisimo mas intuitivo y sencillo de entender, ya que lo que quieres es OBTENER los productos para verlo, y si uno te interesa puedes OBTENER el producto en especifico.

Los verbos de HTTP

Los verbos de HTTP son los que se utilizan para comunicarse con el servidor, y estos verbos son:

GET: Se utiliza para obtener información del servidor.
POST: Se utiliza para enviar información al servidor.
PUT: Se utiliza para actualizar información en el servidor.
DELETE: Se utiliza para eliminar información del servidor.
PATCH: Se utiliza para actualizar parcialmente información en el servidor.
HEAD: Se utiliza para obtener información de la cabecera de una respuesta.
OPTIONS: Se utiliza para obtener información sobre los métodos permitidos por un recurso.
TRACE: Se utiliza para obtener información sobre la ruta de red entre el cliente y el servidor.
CONNECT: Se utiliza para establecer una conexión de túnel con el servidor.

Los parametros de HTTP

Quiza este sumamente acostumbrado a enviar parametros en la URL, como: ?nombre=Omar&apellido=Flores. Pero en REST esto no es lo mas recomendado, ya que se recomienda enviar los parametros en el cuerpo de la petición, ya que los parametros en la URL pueden ser interceptados y leidos por terceros.

Query Parameters: Se utilizan para enviar información al servidor a través de la URL.
- Ejemplo: GET /products?category=electronics.
Path Parameters: Se utilizan para enviar información al servidor a través de la URL.
- Ejemplo: GET /products/123.
Request Body: Se utiliza para enviar información al servidor a través del cuerpo de la petición.
- Ejemplo: POST /products { "name": "iPhone", "price": 999 }.
Request Headers: Se utilizan para enviar información al servidor a través de las cabeceras de la petición.
- Ejemplo Authorization Bearer 123456789.
Request Cookies: Se utilizan para enviar información al servidor a través de las cookies de la petición.
- Ejemplo Cookie: session=123456.
Request Files: Se utilizan para enviar archivos al servidor a través de la petición.
- Ejemplo POST /products { "image": "image.jpg" }.
Response Body: Se utiliza para enviar información al cliente a través del cuerpo de la respuesta.
- Ejemplo GET /products { "name": "iPhone", "price": 999 }.
Response Headers: Se utilizan para enviar información al cliente a través de las cabeceras de la respuesta.
Ejemplo Content-Type: application/json.
Response Cookies: Se utilizan para enviar información al cliente a través de las cookies de la respuesta.
- Ejemplo Set-Cookie: session=123456.
Response Files: Se utilizan para enviar archivos al cliente a través de la respuesta.
- Ejemplo GET /products/image.jpg.
Status Codes: Se utilizan para enviar información al cliente a través del código de estado de la respuesta.
- Ejemplo 200 OK.
Error Codes: Se utilizan para enviar información al cliente a través del código de error de la respuesta.
- Ejemplo 404 Not Found.
Error Messages: Se utilizan para enviar información al cliente a través del mensaje de error de la respuesta.
- Ejemplo Product not found.
Pagination: Se utiliza para enviar información al cliente a través de la paginación de la respuesta.
- Ejemplo GET /products?page=1&limit=10.
Sorting: Se utiliza para enviar información al cliente a través de la ordenación de la respuesta.
- Ejemplo GET /products?sort=name.
Filtering: Se utiliza para enviar información al cliente a través del filtrado de la respuesta.
- Ejemplo GET /products?category=electronics.
Searching: Se utiliza para enviar información al cliente a través de la búsqueda de la respuesta.
- Ejemplo GET /products?q=iphone.

Los códigos de estado de HTTP

Para trabajar con REST es importante conocer los códigos de estado de HTTP, ya que estos códigos se utilizan para comunicar el estado de una petición al cliente. Entiendase que estos códigos son los que se utilizan para saber si la petición fue exitosa, si hubo un error, si se necesita autenticación, etc. Entiendalos y utilicelos correctamente, ya que estos códigos son los que le diran al cliente que esta pasando con la petición.

1xx Informational: Se utiliza para informar al cliente que la petición ha sido recibida y está en proceso.
2xx Success: Se utiliza para informar al cliente que la petición ha sido completada con éxito.
3xx Redirection: Se utiliza para informar al cliente que la petición ha sido redirigida a otro recurso.
4xx Client Error: Se utiliza para informar al cliente que la petición contiene un error del cliente.
5xx Server Error: Se utiliza para informar al cliente que la petición contiene un error del servidor.

Ejemplo

Imagina que haces una peticion para obtener un producto, y el servidor te responde con un 200 OK, esto significa que la petición fue exitosa y el servidor te ha devuelto el producto que pediste. Pero si el servidor te responde con un 404 Not Found, esto significa que el producto que pediste no existe en el servidor.

Principios de REST

Existe unos principios fundamentales para REST, visualice esto como oficialmente las reglas de REST ya que si seguira este patron, debe ser consistente en toda su API para que sea facil de entender y utilizar.

Uniform Interface: La interfaz de la API debe ser uniforme para que sea fácil de entender y utilizar.
Stateless Communication: La comunicación entre el cliente y el servidor debe ser sin estado para que sea fácil de escalar y mantener.
Client-Server Architecture: La arquitectura de la API debe ser cliente-servidor para que sea fácil de implementar y mantener.
Cacheable Responses: Las respuestas de la API deben ser cacheables para que sean rápidas y eficientes.
Layered System: El sistema de la API debe ser en capas para que sea fácil de escalar y mantener.
Code on Demand: El código de la API debe ser bajo demanda para que sea fácil de extender y personalizar.
Hypermedia as the Engine of Application State (HATEOAS): El hipertexto como motor del estado de la aplicación para que sea fácil de navegar y descubrir.
Resource-Oriented Design: El diseño de la API debe ser orientado a recursos para que sea fácil de entender y utilizar.
Representation-Oriented Design: El diseño de la API debe ser orientado a representaciones para que sea fácil de interpretar y transformar.
Message-Oriented Design: El diseño de la API debe ser orientado a mensajes para que sea fácil de enviar y recibir.
Event-Driven Design: El diseño de la API debe ser orientado a eventos para que sea fácil de notificar y reaccionar.

Escrito por: Omar Flores Salazar