API REST: breve guía imprescindible

En esta ocasión os traemos un artículo sobre uno de los conceptos más recurrentes en el mundo del desarrollo de software y que seguro que a mucha gente le sonará. Hablamos de API REST.

¿Qué es API REST?

Lo primero es dejar claro a qué nos referimos cuando hablamos de API REST. Pues bien, literalmente, sus siglas significan REpresentational State Transfer y está definida como un tipo de arquitectura de desarrollo web que se apoya totalmente en el estándar HTTP. Esto nos permite conectar servicios y aplicaciones que entienden dicho protocolo, haciendo esta comunicación mucho más sencilla y estandarizada que otras anteriormente utilizadas, como SOAP, que ya han quedado un poco obsoletas.

Fue definida en el año 2000, es decir este año cumple 20 años, por Roy Fielding, que fue también en su día coautor de la especificación HTTP.

Características de REST

Las APIs son usadas por multitud de plataformas con el fin de intercambiar datos de una forma eficaz y segura. Una de las características que mejor rendimiento proporciona es que es stateless, es decir, que no se guarda en ningún momento el estado en el servidor. Toda la información requerida debe estar en la petición del cliente. 

Para implementar correctamente una API REST con los niveles de calidad suficientes, debemos cumplir el llamado Richardson Maturity Model, que es un modelo que califica un API en función al cumplimiento de las restricciones de la arquitectura REST. 

APIs de nivel 0

El nivel 0 lo hemos comentado anteriormente. Es el no almacenar el estado.

APIs de nivel 1

El nivel 1 es el correcto uso de las URIs. Las URIs tienen que cumplir el siguiente formato:

{protocolo}://{dominio o hostname}[:puerto (opcional)]/{ruta del recurso}?{consulta de filtrado}

A parte de eso deben cumplir una serie de reglas básicas a la hora de ser diseñadas:

• Los nombres no implican una acción, por lo que no se deben usar verbos.
• Deben ser únicas para cada recurso. Para la acción de crear un recurso no sería correcto usar “/usuarios/crear”, ya que existe ya un verbo para ello (POST, hablaremos más adelante)
• Deben ser independientes de formato, es decir, que no sería correcto usar “/documento/321.pdf” sino “/documentos/321”.
• Deben mantener una jerarquía lógica. Esto quiere decir que si estoy accediendo a los contratos de un empleado, no sería correcto “/contratos/empleados/12345”, ya que no respeta la jerarquía. Lo correcto sería “/empleados/12345/contratos”
• Los filtros de los datos para un recurso no deben realizarse en la propia URI. Sino usar Query Params para tal fin.

APIs de nivel 2

El nivel 2 es la correcta aplicación del protocolo HTTP y todo lo que tiene que ver con este protocolo. Esto incluye tres aspectos clave: los verbos o métodos, los códigos de estado de la respuesta y la aceptación de tipo de contenido.

En  cuanto a los métodos o verbos, tenemos que tener en cuenta lo dicho anteriormente: no se deben usar acciones en la URI, porque las acciones están representadas en REST como verbos HTTP. Cada uno tiene la función de indicar que tipo de acción se está llevando a cabo sobre el recurso concreto. Los métodos que nos proporciona HTTP son los siguientes:

• GET: este método está pensado para la lectura de recursos. Es decir, consulta sobre un objeto concreto. Por ejemplo, si queremos obtener los usuarios, debemos implementar un get con la URI “/usuarios”. Si nos referimos a un usuario en concreto, sería “/usuarios/123”, obteniéndolo por id.
• POST: pensado para la creación de nuevos recursos. Si quisiéramos crear un nuevo usuario, llamaríamos al método “/usuarios” con el método post.
• PUT: actualización completa de un recurso concreto. Para la actualización de un usuario, “/usuarios/123” con el método PUT.
• PATCH: actualización parcial de un recurso. Para la actualización de un usuario, “/usuarios/123” con el método PATCH.
• DELETE: utilizado para el borrado de recursos. Para eliminar un usuario, “/usuarios/123” con el método DELETE.
• OPTIONS: utilizado para describir las opciones de comunicación para el recurso de destino.

Los códigos de estado de la petición nos dan la posibilidad de ofrecer una respuesta estandarizada de cómo se ha llevado a cabo la operación a través de un código numérico especialmente diseñado para ello. Se dividen en 5 categorías:

• 1XX – Respuestas informativas: Este tipo de respuestas no son muy comunes. Informan del estado de la petición cuando está inacabada.
• 2XX – Peticiones correctas: Indican que la petición realizada se ha llevado a cabo de forma correcta. 200 que es la estándar, 201 para creación de recursos o 204 para respuestas sin contenido son las más comunes.
• 3XX – Redirecciones: Indica que el cliente tiene que tomar una acción adicional para completar la petición.
• 4XX – Errores de cliente: Se dan cuando es el cliente el que ha cometido un error a la hora de realizar la petición, ya sea por enviar mal el cuerpo de la misma, o método o simplemente no está autorizado a realizar dicha acción.
• 5XX – Errores del servidor: en este caso es el servidor el que produce el error y devuelve este tipo de códigos. Puede ser porque el servidor no esté disponible.

Y en cuanto al tipo de contenido, HTTP nos permite elegir qué tipo de contenido aceptamos tanto en la petición como en la respuesta. Esto se lleva a cabo a través de la cabecera Content-Type, pudiendo ser XML o JSON, así como cualquier formato de fichero como pdf.

APIs de nivel 3

Por último, tenemos el nivel 3, que es HATEOAS, Hypermedia as the Engine of Application State (hipermedia como motor del estado de la aplicación). Esto básicamente significa que debemos mostrar las URIs de forma que el cliente esté menos acoplado al servidor y no sea necesario hacer cambios en estos casos. Es decir, enviar como parte de la respuesta, las URLs posibles a la que puede acceder a más información de esos datos. Por ejemplo, si pedimos los datos de un usuario, no vamos a devolver todos sus pedidos, pero si las urls a las que el cliente debe llamar para obtener más información. Por ejemplo:

{“id”:1, :“nombre”:”Juan”, “edad”:26, “pedidos”:”/usuarios/1/pedidos” }

De esta forma, los clientes no tienen que conocer previamente la API de una forma tan completa, desacoplando más al cliente y la API.

Otra cosa importante a tener en cuenta en las APIs es el versionado. Utilizar versiones en las APIs nos permite realizar cambios de formato sin afectar a aquellos clientes que estén usando el anterior. La forma más común de hacerlo es con un prefijo en la propia URI:

GET /v1/usuarios

GET /v2/usuarios

En el caso de que cambiemos algo, los cambios no afectarán a quien use la antigua versión, pudiendo seguir usando la v1, mientras los que quieran pueden adaptarse a la nueva v2 sin problema.

Ejemplos de API REST

Hay multitud de aplicaciones que exponen sus APIs de forma pública para ofrecer su funcionalidad a terceros y que estos puedan desarrollar nuevos servicios a partir de otros ya existentes. Una de ellas, de las más conocidas, es la API de Spotify. Con una documentación muy completa es de las APIs mas usadas para aprender. 

Otra muy usada es la de Twitter, permitiendo crear aplicaciones cliente de Twitter no oficiales y que mucha gente usa por delante del oficial, como TweetDeck.

Para que podáis trastear con APIs de uso libre os dejamos por aquí un enlace de Github con infinidad de APIs públicas. También os recomendamos nuestra selección de APIs para desarrolladores Front End.

Con estos principios básicos aquí expuestos estás listo para comenzar a crear tus propias APIS o a consumir las de terceros con un poco más de conocimiento. ¡Anímate y comparte tu experiencia a través de las redes sociales!