Rest
Introducción¶
REST (Representational State Transfer, o transferencia de estado representacional) es un estilo de arquitectura software utilizado para diseñar aplicaciones de web distribuidas.
Se basa en los siguientes principios o restricciones:
- Cliente - Servidor.
- Sin estado. La comunicación entre cliente y servidor debe ser sin estado.
- Sistema por capas. Entre el cliente y el servidor pueden existir múltiples capas como pasarelas, proxies o cortafuegos.
- Caché. Las respuestas del servidor se deben poder declarar como cacheables o no cacheables.
- Interfaz uniforme.
- Código a demanda. Los clientes pueden extender su funcionalidad descargando y ejecutando código a demanda. Esta restricción es opcional.
Las aplicaciones que cumplen estas restricciones se consideran RestFul.
El protocolo HTTP¶
Cuando se introduce una URL como https://www.google.com en el navegador, se envía una solicitud (request) al servidor identificado por la URL. Este servidor responde con una respuesta (response). El formato de estas solicitudes y respuestas esta definido por el protocolo HTTP (Hyper Text Transfer Protocol).
Cuando se escribe una URL en el navegador, éste envía una petición GET al servidor identificado. El servidor entonces contesta con una petición HTTP que contiene datos en HTML (Hyper Text Markup Language). El navegador toma este HTML y lo visualiza en la pantalla.
En el caso de cumplimentar un formulario cuando se da al botón de Enviar, la petición que se envía al servidor es POST.
Métodos de solicitudes HTTP¶
El método utilizado en la solicitud HTTP indica qué acción se quiere realizar con dicha solicitud. Los más importantes son:
- GET. Recupera detalles de un recurso.
- POST. Crea un nuevo recurso.
- PUT. Actualiza un recurso existente.
- DELETE. Borra un recurso.
Otros son PATCH, OPTIONS o HEAD.
Códigos de estado de respuesta HTTP¶
En toda respuesta HTTP se envía siempre un código de estado. Algunos ejemplos son:
- 200: Éxito.
- 404: Página no encontrada.
Recursos¶
Un recurso es algo que puede ser accedido o manipulado.
Los recursos se pueden identificar mediante URI (Uniform Resource Identifier).
La sintaxis de un URI es: esquema:parte-específica-del-esquema
Representación¶
Los recursos RESTful son entidades abstractas. Los datos y metadatos que generan un recurso RESTful se tienene que serializar en una representación antes de enviarlos al cliente.
El mismo recurso puede tener varias representaciones. Estas representaciones pueden estar en formatos tipo texto (formatos HTML, XML o JSON) o binarios (PDFs, JPGEGs o MP4s). El cliente puede solicitar una representación en concreto, es lo que se denomina negociación del contenido.
💡 JSON se ha convertido en el formato estándar de facto para los servicios REST.
Métodos HTTP¶
En la Web, el estándar HTTP provee ocho métodos (o verbos) HTTP que permiten a los clientes interactuar y manipular recursos.
Los métodos más utilizados son GET, POST, PUT y DELETE.
Seguridad¶
Se dice que un método HTTP es seguro si no provoca ningún cambio en el estado del servidor, como GET o HEAD.
Idempotencia¶
Una operación se considera idempotente si produce el mismo estado del servidor tanto si se aplica una como varias veces. Los métodos GET, HEAD, PUT y DELETE son idempotentes.
GET¶
El método GET recupera la representación de un recurso.
Es seguro e idempotente, y las respuestas se pueden cachear.
Además de la representación, la respuesta a la petición GET incluye los metadatos asociados con el recurso. Estos metadatos se representan en una secuencia de valores clave-valor llamados cabeceras HTTP.
Ejemplo: Respuesta a una petición GET a http://blog.example.com/posts/1:
]
HEAD¶
Se utiliza cuando un cliente quiere comprobar si un recurso está disponible y no le importa su representación. También se utiliza cuando el cliente quiere saber si existe una nueva versión del recurso antes de descargarlo.
El método HEAD solo devuelve los metadatos asociados al recurso, sin enviar la representación.
Es seguro e idempotente, y las respuestas se pueden cachear.
DELETE¶
Pide que se borre un recurso. Dependiendo de la implementación del servicio, el borrado puede ser físico o no.
Si el borrado es satisfactorio, las futuras peticiones GET recibirán un error Resource not found vía el código de estado HTTP 403.
No es seguro, pero sí idempotente.
PUT¶
Permite a los clientes modificar el estado de un recurso. El cliente modifica el estado de un recurso y envía la representación actualizada al servidor usando un método PUT; al recibir la petición el servidor reemplaza el estado del recurso con el nuevo estado.
No es seguro, pero sí idempotente.
POST¶
Se usa para crear recursos. Habitualmente, se usa para crear recursos bajo subcolecciones (colecciones de recursos que existen bajo un recurso padre).
Al contrario que PUT; POST no necesita conocer la URI del recurso. El servidor es el responsable de asignar un ID al recurso y decidir la URI.
El método POST es muy flexible y se utiliza cuando ningún otro método resulta apropiado.
No es seguro ni idempotente.
PATCH¶
Se utiliza para hacer actualizaciones parciales de un recurso. Al contrario que PUT, no necesita enviar la representación completa del recurso.
Modelo de madurez de Richardson¶
Clasifica los servicios web basados en REST según cumplen los principios REST.
Nivel 0¶
Los servicios usan HTTP como mecanismo de transporte y hacen las llamadas a procedimientos remotos en una única URI.
Se suelen usar los métodos GET y POST.
Están en este nivel SOAP y los servicios web basados en XML-RPC.
Nivel 1¶
Se introducen múltiples URIs, uno por recurso. Los endpoints con funcionalidad compleja se descomponen en múltiples recursos. Sin embargo, los servicios en esta capan usan un verbo HTTP, normalmente POST, para realizar todas las operaciones.
Nivel 2¶
Los servicios de este nivel aprovechan el protocolo HTTP haciendo uso de los verbos y códigos de estado HTTP.
Los servicios web que implementan operaciones CRUD son ejemplos de nivel 2.
Nivel 3¶
Es el nivel más maduro para un servicio, se construye alrededor del concepto de HATEOAS. Los servicios en este nivel permiten el descubrimiento proveyendo respuestas que contienen enlaces a otros recursos relacionados, indicando al cliente qué hacer a continuación.
Construyendo una RESTful API¶
Una RESTful API bien diseñada permite a los usuarios finales consumir la API de forma sencilla y facilita su adopción.
A un alto nivel, los pasos para construir una RESTful API son:
- Recursos
Se empieza identificando los recursos de interés para los consumidores. A menudo, estos recursos coinciden con las entidades de la aplicación. - Puntos finales
El siguiente paso es diseñar URIs que mapeen los recursos a endpoints. - Acciones
Identificar los métodos HTTP que se pueden usar para realizar las operaciones en los recursos. - Respuestas
Identificar la representación soportada para las peticiones y responder con el código de estado apropiado.
Ejemplo de Rutas RESTful¶
| Name | Path | HTTP Verb | Purpose | Mongoose Method |
|---|---|---|---|---|
| Index | /dogs | GET | List all dogs | Dog.find() |
| New | /dogs/new | GET | Show new dog form | N/A |
| Create | /dogs | POST | Create a new dog, then redirect somewhere | Dog.create() |
| Show | /dogs/:id | GET | Show info about one specific dog | Dog.findById() |
| Edit | /dogs/:id/edit | GET | Show edit form for one dog | Dog.findById() |
| Update | /dogs/:id | PUT | Update particular dog, then redirect somewhere | Dog.findByIdAndUpdate() |
| Destroy | /dogs/:id | DELETE | Delete a particular dog, then redirect somewhere | Dog.findByIdAndRemove() |