Diseño de un api ReST

En la actualidad existen muchas tecnologías para publicar servicios y componer una arquitectura cliente-servidor. ReST es probablemente la más extendida y es difícil encontrar un sitio en el que no se esté usando. En este post veremos las bases de ReST y explicaremos como diseñar un api que sea aceptablemente ortodoxa.

Cables azules para las peticiones GET. Cables blancos para las POST

El protocolo HTTP

La idea que hay detrás del protocolo HTTP es sencilla y particular: en un servidor existen una serie de recursos guardados en directorios reales o imaginarios. Después los clientes envían peticiones en las que se incluye una ruta a uno o varios de esos recursos junto con un verbo que indica que acción debe realizarse una vez estos hayan sido localizados.

Otras características de HTTP que lo hacen muy conveniente como protocolo de comunicación entre cliente-servidor son:

• Mensajes sencillos: Los mensajes HTTP son textos planos con apenas estructura. Una cabecera con información sobre la petición y un cuerpo opcional. Es tan sencillo que la separación entre cabecera y cuerpo son dos saltos de línea y retorno de carro seguidos.

• Independiente del formato de la información intercambiada. Puede ser xml, json, una imagen, html o cualquier cosa que se nos pase por la cabeza.

• Sin estado: La conversación más larga que puede mantenerse con HTTP es petición-respuesta, precisamente porque HTTP está pensado para aplicaciones distribuidas que trabajan con los recursos alojados en un servidor. El servidor no almacenará estado alguno ni dedicará recursos en ello (por ejemplo creando sesiones). Si es necesario mantener un estado esta tarea recaerá sobre las aplicaciones cliente.

Esta última característica tiene una gran importancia a la hora de diseñar un api ReST y todas las funcionalidades que ofrezca el servidor deberán tenerla en cuenta.

ReST

De Representational State Transfer, es una arquitectura de software para aplicaciones cliente-servidor ideada por Roy T. Fielding cuya principal característica es que utiliza el protocolo HTTP hasta la última consecuencia. Toda la información que maneje el servidor será representada como recursos y cualquier funcionalidad ofrecida por este deberá poder accederse a través de una petición HTTP que respete los principios del protocolo al pie de la letra. 

Roy T. Fielding diciendo lo que es ReST y lo que no.

Los recursos

Lo primero que definiremos cuándo diseñamos un api ReST son los recursos. Estos serán la información que maneje nuestro servicio. Ejemplos típicos (y tópicos) de recursos podrían ser clientes, facturas, productos, empleados... Cada uno de estos recursos deberá identificarse con un valor único y poseerá distintas propiedades. Por ejemplo: los clientes tendrán id, nombre, DNI, fecha de nacimiento y los productos id, referencia, fabricante, peso, etc.

Decidir cuáles son los recursos resulta más sencillo cuando ya disponemos de una base de datos o la lógica de la aplicación. Es la norma que exista una relación entre las tablas que tengamos y los recursos del servicio. Esto también ocurrirá con respecto a las entidades que utilice nuestra lógica de negocio. Además descubriremos que las relaciones entre esas tablas o entidades se ve reflejada en las relaciones existentes entre los recursos. Pero no nos confundamos: ¡un api ReST es una abstracción que a simple vista nada tiene que ver con un diagrama de clases o de entidad-relación!

La representación de los recursos

Una vez identificados los recursos debemos decidir cómo los representaremos en las peticiones y respuestas. HTTP permite cualquier formato, pero normalmente podremos escoger entre XML y JSON debido a que los frameworks suelen tener en cuenta únicamente esos dos formatos. Si escogemos otra manera de representar a los recursos nos tocará hacer las debidas conversiones con nuestro propio código.

La inmensa mayoría de servicios ReST trabajan con JSON puesto que contienen la misma información que un XML pero son más sucintos, a costa de no incluir ninguna descripción de la información que contienen. Veámoslo con un ejemplo:

Lucha de acrónimos

En el XML vemos que hay claramente una lista de clientes. En JSON básicamente sustituimos cada etiqueta xml por un único carácter. Cierto que no queda claro que se trate de clientes y bien pudieran ser ‘empleados’ o ‘personas’ pero no debemos olvidar que en un servicio ReST tenemos una aplicación cliente que es capaz de saber que está solicitando un listado de clientes, no de empleados. El XML en este caso es un despilfarro de ancho de banda.

Las rutas

El siguiente paso una vez que conozcamos cuáles son nuestros recursos será definir las rutas para localizarlos. Debemos ‘colocarlos’ en esos directorios de los que nos habla el protocolo HTTP y es el momento de hacer un inciso relacionado con ellos.

En HTTP localizamos los recursos utilizando URLs. Con una URL identificamos un recurso, su localización y el modo en el que accederemos a él.

http://ip_servidor:puerto/ruta/identificador_recurso

En la ruta encontramos los directorios en los que se localiza el recurso identificado por el valor final. Cuando se trata de recursos físicos esos directorios existen realmente. Es lo que sucede, por ejemplo, con un servidor web. En Apache (el servidor web más utilizado) disponemos del directorio ‘www’ dentro del cual organizamos nuestros ficheros .html, .css, imágenes y demás cacharrería. Cuando los recursos son abstractos, representaciones de filas en una tabla u objetos en la memoria del servidor, los situaremos en directorios ficticios para ‘seguirle el juego’ al protocolo HTTP.

Recursos físicos en un servidor Apache de color azul

Una técnica que nos ayuda a definir las rutas es imaginarnos los recursos realmente como ficheros y realizarnos la siguiente pregunta: Si tuviera una serie de ficheros, a razón de uno por ‘Empleado’ ¿en qué directorio los guardaría? ¿Y si fueran facturas, productos o cualquier otra cosa? La respuesta es clara: en los directorios ‘empleados’, ‘facturas’ y ‘productos’.

Los métodos

En HTTP una petición es una ruta a los recursos más una acción, el método. De todos los métodos definidos en HTTP los cinco que sirven para actuar sobre los recursos son

• GET: se solicitan recursos existentes en el servidor
• POST: añade un nuevo recurso en la ruta indicada
• PUT: Sustituye el recurso indicado por la url por el que se envía. Si no existe lo añadirá.
• PATCH: Modifica el recurso utilizando los datos adjuntos a la petición.
• DELETE: Elimina los recursos indicados en la url.

En realidad los métodos no hacen nada…todo depende de la implementación del servicio en el lado del servidor. Vamos a suponer que nadie programará que al recibir un GET se elimine un recurso y que cuando se reciba un DELETE se entregen. Suena absurdo, pero es perfectamente posible hacerlo así.

Con esto ya tenemos la base de que es un servicio ReST. En el siguiente post comenzaremos con el diseño de un api sencilla.

Jordan Peterson después de haber leído este artículo