Descripción general de REST. Parte 2: Comunicación entre un cliente y un servidor

Descripción general de REST. Parte 1: ¿Qué es REST? En esta parte, profundizaremos en cómo se lleva a cabo la comunicación entre un cliente y un servidor. En el camino, descubriremos nuevos términos y los explicaremos. Para asegurarnos de que todo esté claro, analizaremos la comunicación cliente-servidor usando una aplicación RESTful como ejemplo. Supongamos que estamos desarrollando una aplicación web que almacena información sobre los clientes y sus pedidos. En otras palabras, nuestro sistema puede realizar operaciones en ciertas entidades: crearlas, editarlas y eliminarlas, y mostrar información sobre ellas. Estas entidades serán:

• clientes (clientes)
• pedidos (pedidos de clientes)
• artículos (productos)

En una arquitectura RESTful, los clientes envían solicitudes a un servidor para recuperar o modificar datos y luego los servidores envían respuestas a sus solicitudes.

Peticiones

Las solicitudes de los clientes casi siempre se realizan mediante el protocolo HTTP. En general, las solicitudes HTTP constan de varios componentes:

• método HTTP
• encabezamiento
• URI
• cuerpo de solicitud

A continuación consideraremos cada componente con mayor detalle.

URI y recursos

Los datos que los clientes reciben o modifican a través de solicitudes se denominan recursos. La comunicación cliente-servidor tiene que ver con la manipulación de recursos. En REST, los recursos son cualquier cosa a la que le puedas dar un nombre. En cierto sentido, son como clases en Java. En Java, podemos crear una clase para cualquier cosa. Entonces, en REST, un recurso puede ser cualquier cosa: un usuario, un documento, un informe, un pedido. Puede ser una abstracción de alguna entidad o algo específico, por ejemplo, una imagen, video, animación o archivo PDF. En nuestro ejemplo, tenemos 3 recursos:

• clientes (clientes)
• pedidos (pedidos de clientes)
• artículos (productos)

Los clientes envían solicitudes a ubicaciones de recursos conocidas como puntos finales. En pocas palabras, un punto final es como una dirección en la red. Profundizando más, podemos decir que un punto final es un URI, es decir, una secuencia de caracteres que identifica un recurso abstracto o físico. Identificador uniforme de recursos (URI) A veces, un punto final, o URI, se denomina ruta, es decir, la ruta a un recurso. A los efectos de este artículo, utilizaremos el término URI. Cada recurso específico debe tener un URI único. El desarrollador del servidor es responsable de garantizar que cada recurso tenga siempre su propia URI. En nuestro ejemplo, somos los desarrolladores, así que lo haremos de la forma que sepamos. Así como suele ser habitual asignar identificadores numéricos como claves principales en una base de datos relacional, cada recurso también tiene su propia ID en REST. El ID de recurso en REST a menudo coincide con el ID del registro en la base de datos que almacena información sobre el recurso. Los URI REST suelen comenzar con la forma plural de un sustantivo que describe algún recurso. Por ejemplo, "

• /clientes — URI de todos los clientes disponibles
• /customers/23 — URI de un cliente específico, es decir, el cliente con ID=23
• /customers/4 — URI de un cliente específico, es decir, el cliente con ID=4.

Pero eso no es todo. Podemos extender la URI agregando pedidos:

• /customers/4/orders — URI de todos los pedidos realizados por el cliente n.º 4
• /customers/1/orders/12 — URI del pedido n.° 12 realizado por el cliente n.° 1.

Si continuamos la expansión agregando más productos, obtenemos:

• /customers/1/orders/12/items — URI de la lista de todos los productos en el pedido No. 12 realizado por el cliente No. 1.

A medida que agregamos niveles de anidamiento, lo importante es hacer que los URI sean intuitivos.

método HTTP

El método HTTP es una secuencia de cualquier carácter (excepto los caracteres de control y los delimitadores), que indica la operación principal que se está realizando en el recurso. Hay varios métodos HTTP comunes. Vamos a enumerar los que se utilizan con más frecuencia en los servicios RESTful:

• GET — Obtener información sobre un recurso en particular (a través de su ID) o sobre una colección de recursos
• POST — Crear un nuevo recurso
• PUT — Cambiar un recurso (a través de su ID)
• DELETE — Eliminar un recurso (a través de su ID)

Encabezados

Las solicitudes, así como las respuestas, contienen encabezados HTTP. Transmiten información adicional sobre la solicitud (o respuesta). Los encabezados son pares clave-valor. Puede ver la lista de los encabezados más comunes en Wikipedia . En cuanto a REST, los clientes suelen enviar un encabezado "Aceptar" en las solicitudes al servidor. Este encabezado es necesario para decirle al servidor en qué formato el cliente espera recibir una respuesta. Se dan varios formatos en una lista de tipos MIME. MIME (Extensiones de correo de Internet multipropósito) es una especificación para codificar información y formatear mensajes para que puedan enviarse a través de Internet. Cada tipo MIME consta de dos partes separadas por una barra: un tipo y un subtipo. Ejemplos de tipos MIME para diferentes tipos de archivos:

• texto — texto/sin formato, texto/css, texto/html
• imagen — imagen/png, imagen/jpeg, imagen/gif
• audio — audio/wav, audio/mpeg
• vídeo — vídeo/mp4, vídeo/ogg
• aplicación — aplicación/json, aplicación/pdf, aplicación/xml, aplicación/octet-stream

Por ejemplo, una solicitud puede tener un encabezado como este:

Accept:application/json

Este encabezado le dice al servidor que el cliente espera recibir una respuesta en formato JSON.

cuerpo de la solicitud

Este es el mensaje enviado por el cliente al servidor. Si la solicitud tiene un cuerpo o no, depende del tipo de solicitud HTTP. Por ejemplo, las solicitudes GET y DELETE generalmente no contienen ningún cuerpo de solicitud. Pero las solicitudes PUT y POST pueden, solo depende del propósito de la solicitud. Después de todo, para recibir y/o eliminar datos usando una ID (que se pasa en la URL), no necesita enviar datos adicionales al servidor. Pero para crear un nuevo recurso (a través de una solicitud POST), debe enviar el recurso. Lo mismo se aplica a la modificación de un recurso existente. En REST, el cuerpo de la solicitud suele enviarse en formato XML o JSON. El formato JSON es el más común. Supongamos que queremos enviar una solicitud al servidor para crear un nuevo recurso. Si no lo has olvidado, consideramos el ejemplo de una aplicación que gestiona los pedidos de los clientes. Digamos que queremos crear un nuevo cliente. En nuestro caso, almacenamos la siguiente información del cliente: Nombre, correo electrónico, número de teléfono. Entonces el cuerpo de la solicitud podría ser el siguiente JSON:

{
  "name" : "Amigo",
  "email" : "amigo@jr.com",
  "phone" : "+1 (222) 333-4444"
}

Juntando solicitudes

Entonces, hemos examinado lo que podría haber en la solicitud de un cliente. Ahora daremos algunos ejemplos de solicitudes junto con descripciones.

Respuestas

Digamos algunas palabras sobre las respuestas del servidor. Una respuesta generalmente consta de las siguientes partes:

• código de respuesta
• encabezados
• cuerpo de respuesta

En general, los encabezados de respuesta no son muy diferentes de los encabezados de solicitud. Además, algunos encabezados se usan tanto en respuestas como en solicitudes. Creo que todo está claro también con respecto al cuerpo de la solicitud. El organismo suele devolver información solicitada por el cliente. La información devuelta en respuesta a las solicitudes GET también puede estar en formato JSON. Pero la última parte es un poco más interesante.

Códigos de respuesta HTTP

Consideremos los códigos de respuesta HTTP con más detalle. Un código de estado HTTP es parte de la primera línea de una respuesta del servidor a las solicitudes realizadas a través del protocolo HTTP. Es un número entero que consta de tres dígitos decimales. El primer dígito indica la clase del código de estado de respuesta. El código de respuesta suele ir seguido de una frase explicativa en inglés, separada por un espacio. Esta frase es una razón legible por humanos para la respuesta. Ejemplos:

• 201 Creado
• 401 no autorizado
• 507 Almacenamiento insuficiente

El código de respuesta le dice al cliente el resultado de la solicitud y le permite determinar qué acciones tomar a continuación. Los códigos de respuesta se dividen en varias clases o grupos:

• 1XX — Informativo
• 2XX : estos códigos indican que la solicitud del cliente se recibió y procesó correctamente
• 3XX : estos códigos informan al cliente que se debe realizar una solicitud adicional, generalmente a un URI diferente, para completar con éxito la operación.
• 4XX : error del cliente. Dichos códigos pueden resultar de una solicitud redactada incorrectamente. Otro ejemplo es el conocido código "404 Not Found", que puede ocurrir cuando un cliente solicita un recurso inexistente
• 5XX : error del servidor. Estos códigos se devuelven al cliente si el servidor es responsable de la falla de la operación

Descripción general de REST. Parte 3: Creación de un servicio RESTful en Spring Boot