Qué es una API REST

Todo desarrollador ha escuchado hablar alguna vez del concepto de API y de la metodología REST. Sin embargo, en ocasiones pueden resultar ser conceptos un tanto confusos que no se entienden al 100%. En este tutorial vamos a explicar detalladamente qué es una API REST.

Qué es una API REST

REST es el acrónimo de Representational State Transfer, que describe los estándares de una arquitectura de servicios web. En concreto, se define el modo en el que se deben compartir los datos entre diferentes sistemas que implementan la arquitectura REST, también conocida como RESTful.

La arquitectura REST no es ni un lenguaje ni un framework, sino un concepto que define una metodología a seguir durante el desarrollo de los diferentes sistemas de una aplicación.

Para explicarlo de otro modo, vamos a poner los ejemplos de un videoclub que alquila películas físicas y de un servicio de streaming. En el videclub, las películas deben ser duplicadas cada vez que un cliente pide una determinada película. En cambio, en el caso del servicio de streaming, existe una única película que se sirve a través de Internet hasta cada uno de los clientes que usa el servicio, siendo este último un servicio RESTful.

El término API es un acrónimo de Application Programming Interface, que no es otra cosa que una interfaz que permite que dos sistemas o aplicaciones se comuniquen entre sí. En consecuencia, deducimos que una API REST es una API que sigue la filosofía REST.

Una API web consta en general de dos acciones básicas, que son la petición al servidor y la respuesta del mismo. Cuando se trata de la comunicación entre dos sistemas, la parte visual no es relevante, por lo que, cuando se realiza una petición a un endpoint del servidor, este suele responder con datos en un formato determinado, como por ejemplo XML o JSON.

Arquitectura de una API REST

Una API REST debe cumplir una serie de principios o restricciones para que pueda ser considerada como una API RESTful:

• Arquitectura cliente servidor: El cliente será el encargado de realizar una petición al servidor, que consiste en una acción a realizar junto con los datos necesarios para procesar la petición. El servidor será el encargado de procesar la petición del cliente y proporcionar una respuesta.
• Identificación de recursos: La identificación de cada elemento debe ser uniforme para todos los recursos disponibles en una API. En el caso de una API HTTP, se usa la URL para identificar a los recursos. Por ejemplo, en el caso de un servicio de streaming de cine, identificaremos a las diferentes películas mediante la URL.
• Interacciones stateless. Es decir, que el servidor no debería necesitar hacer referencia a peticiones anteriores para procesar la petición actual, no siendo necesario el uso de sesiones. Toda la información de una petición deberá estar descrita en la propia petición. De ahí deriva el termino stateless, que significa «sin estado», de modo que no es necesario mantener un estado en el servidor para procesar próximas peticiones.
• Sistema de capas: Se acepta el uso de diferentes capas que pueden actuar durante las peticiones. Por ejemplo, el cliente puede no siempre conectarse al mismo servidor, ya que las peticiones pueden ser redireccionadas a diferente servidores mediante balanceadores de carga. Los balanceadores de carga o load balancers suelen redirigir la peticiones a varios servidores en función de lo cargados que estén, acelerando así el tiempo de respuesta.
• Uso de caché: El servidor puede mantener la respuestas a las peticiones en caché, por lo que las acciones que se llevarán a cabo pueden no ser siempre las mismas.

Adicionalmente, también existe un principio opcional conocido como code on demand, que significa código bajo demanda. Este principio indica que el cliente puede descargarse opcionalmente código del servidor para disponer de más funcionalidades. Sin embargo, el cliente podría no poder ejecutarlo, de ahí que sea opcional.

Vamos a centrarnos ahora en las APIs REST en el contexto del desarrollo de aplicaciones web. Como sabes, las URLs suelen comenzar por HTTP o por HTTPS, dependiendo del protocolo a utilizar.

El término HTTP se compone de las siglas de HyperText Transfer Protocol, que significa protocolo de transferencia de hipertexto, que no es otra cosa el protocolo que define la comunicación entre un cliente y un servidor en Internet.

El protocolo HTTP utiliza conexiones TCP para conectarse a un puerto del servidor, que suele ser el puerto 80 si usamos el protocolo HTTP o el puerto 443 si usamos el protocolo HTTPS. Una petición constará siempre de una URL, un método, una serie de cabeceras y un cuerpo o body. Por ejemplo, cuando realizas una petición mediante tu navegador estás realizando peticiones GET de obtención de datos o recursos. Sin embargo, cuando envías un formulario, realizarás una petición POST de envío de datos desde tu navegador, que permitirá la creación de recursos o datos en el servidor.

Al recibirla, el servidor procesará la petición recibida y enviará una respuesta que constará de un estado y de un body como elementos fundamentales. Por ejemplo, cuando accedes a una página de error con tu navegador, seguramente estés acostumbrado a ver el estado 400. Cuando una petición se procesa correctamente, el estado recibido es el 200 aunque no se muestre explícitamente en tu navegador.

A continuación vamos a explicar en detalle tanto las peticiones como las respuestas.

Peticiones REST: Request

Las peticiones HTTP pueden ser de diferentes tipos, definidos mediante su acción. A continuación puedes ver una lista con los tipos de peticiones HTTP más comunes que se suelen implementar en una API:

• GET: El método GET se utiliza para obtener recursos mediante una petición a la API, implicando la lectura de uno o más recursos en el servidor en base a los parámetros especificados en la URL. Una petición GET nunca alterará el estado de los datos en el servidor, siendo únicamente una operación de lectura.
• POST: El método POST se utiliza para crear recursos mediante una petición a la API, implicando la creación de un recurso en el servidor en función de los datos enviados al mismo. Cuando te registras en una red social o cuando creas contenido en ellas, realizas una petición POST. Este tipo de petición suele implicar una escritura de datos en un archivo del servidor o en una base de datos.
• PUT: El método PUT se utiliza para actualizar recursos mediante una petición a la API. Este tipo de petición suele implicar tanto la lectura como la escritura de un recurso en el servidor. Una misma petición PUT realizada múltiples veces de forma consecutiva producirá siempre el mismo resultado, motivo por el que se dice que las peticiones PUT son idempotentes.
• PATCH: El método PATCH también se utiliza para actualizar recursos mediante una petición a la API, aunque a diferencia del método PUT, el método PATCH se usa para actualizar ciertas propiedades de un recurso, en lugar de reemplazarlas todas.
• DELETE: El método GET se utiliza para obtener recursos mediante una petición a la API implicando la eliminación un recurso en el servidor, identificado mediante los parámetros proporcionados en la URL.

Los métodos definidos en las peticiones HTTP de esta lista se corresponden con los del paradigma CRUD, que son los métodos de lectura, escritura, eliminación y actualización utilizados en una base datos.

Respuestas REST: Response

Cuando el servidor recibe una petición HTTP y la procesa, devolverá una respuesta HTTP que incluirá los siguientes elementos básicos:

• Cabeceras: También conocidas como headers, son metadatos acerca del contenido devuelto y del resultado de la petición.
• Body: También conocido como cuerpo, el body incluye los datos devueltos por la petición. Si por ejemplo hemos pedido los datos de un usuario, estos se devolverán en el body.
• Estado: Las respuestas HTTP incluyen un código numérico de respuesta, también conocido como status code, que en función de su valor, proporcionan información acerca del resultado de la petición.

Además de proporcionarnos información acerca del resultado de una operación, el código de estado también nos dice si se requieren más operaciones o no para completar la operación. Los códigos de estado suelen constar de tres dígitos, que pueden clasificarse como los siguientes tipos:

• Información: Los códigos de respuesta que comienzan por 1 nos proporcionan información acerca de una petición, sin tratarse de la respuesta a la petición en sí misma.
• Éxito: Los códigos de respuesta que comienzan por 2 indican que la operación que se corresponde con la petición ha sido realizada con éxito. Por ejemplo, cuando accedes a una página con éxito, el código que se devuelve es el 200.
• Redirección: Los códigos de respuesta que comienzan por 3 indican que se ha producido una redirección de un recurso a otro. Por ejemplo, el código 301 «Moved Permanently» se usa para redireccionar un página a otra URL.
• Error en le petición: Los códigos de respuesta que comienzan por 4 se usan para indicar un error en la petición o durante el proceso de la misma. Por ejemplo, si una página o recurso al que se accede no existe en la base de datos del servidor, se devuelve el código 400 «Not Found».
• Error en el servidor: Los códigos de respuesta que comienzan por 5 se usan para indicar que se ha producido un error en el servidor. Por ejemplo, el código de error 500 «Internal Server Error» es devuelto automáticamente por muchos servidores cuando se produce un error inesperado durante la ejecución del código del propio servidor.

En cuanto a los códigos de respuesta que se corresponden con las operaciones REST de una API, deberían ser los siguientes, en función del tipo de petición:

Los códigos de esta lista se usan cuando la petición se ha procesado correctamente. El código 200 indica que la petición se ha completado con éxito, siendo usado en peticiones GET, PUT, PATCH y DELETE. El código 201 se usa únicamente en peticiones POST, indicando que el recurso se ha creado correctamente.

Tal y como ves, las peticiones DELETE pueden devolver varios códigos de respuesta válidos. El código 200 se suele usar cuando el recurso se ha borrado correctamente, mientras que el 202 se usa cuando el recurso se ha marcado para ser borrado, pudiendo este haberse borrado o no. Finalmente, el código 204 se usa cuando el recurso indicado no existe.

Implementación de una API REST

Cuando creas una API en un servidor, crearás endpoints, que son las URLs a las que deben apuntar las peticiones HTTP. Dado que sería impracticable crear endpoints individuales para cada uno de los recursos de una aplicación, la creación de rutas suele facilitarse con ciertas herramientas cuando usas algún framework como Laravel, Express o SCIWP, pudiendo definir su estructura.

Estructura de un endpoint

Un endpoint suele aceptar uno o más verbos GET, POST, PUT, PATCH o DELETE, estando compuestos de una raíz, una ruta o path y opcionalmente de una consulta o query string:

• Raíz: Lar raíz es la URL que se establece como base para una API, que suele constar del protocolo (HTTP / HTTPS), del dominio y de un número de versión. Por ejemplo, la URL https://dominio.com/v2 consta del protocolo HTTPS, del dominio dominio.com y del número de versión v2.
• Ruta: La ruta es la estructura o localización de un recurso. Por ejemplo, la ruta /peliculas identificaría a un conjunto de películas, mientras que la ruta /peliculas/2 identificaría a la película cuyo identificador es 2. Sin embargo, es habitual usar estructuras somo /peliculas/{id} a la hora de definir una ruta, dependiendo del framework que se utilice.
• Consulta: Son los pares de valores GET definidos en una URL, que suelen usarse para ordenar, filtrar o paginar los valores obtenidos. Por ejemplo, la consulta ?page=2 suele usarse para obtener la segunda página de un conjunto de recursos paginados.

El resultado de los ejemplos que hemos definido darían lugar a los endpoints https://dominio.com/v2/peliculas?page=2 o https://dominio.com/v2/peliculas/2. El primer endpoint devolvería todas las películas que estén en la segunda página del conjunto de películas.  Es decir, que si las páginas contienen 10 elementos, se mostrarían los elementos que van del 10 al 20. Por otro lado, el segundo endpoint devolvería únicamente la película cuyo identificador es 2.

Convenciones establecidas

Existen una serie de convenciones o estándares que deberías aplicar cuando crees una API REST. El uso de estándares hace que el código se más sencillo de mantener y de testear.

Por ejemplo, en cuanto a la sintaxis de las rutas, estas únicamente deberían estar compuestas de caracteres en minúscula y de guiones, siguiendo la notación kebab-case. El uso de caracteres en mayúscula o de guiones bajos está mal considerado.

Los nombres de las rutas deberían estar siempre en plural aunque identifiquen a un único elemento:

• La ruta /mensajes es la que se usará para obtener varios mensajes.
• Lara ruta /mensajes/2 es la que se usará para obtener el mensaje cuyo identificador es 2. No deberías usar la ruta /mensaje/2, ya que podría confundir tanto a desarrolladores como a terceros que creen aplicaciones que consuman la API.

Las rutas de un endpoint debería contener únicamente nombres el lugar de verbos:

• La ruta que se usa para obtener un mensaje, debería ser /mensajes/5 en lugar de /mensajes/2/get, ya que la acción ya se especifica mediante el tipo de petición, que debería ser GET.
• La ruta utilizada para crear un mensaje, debería ser /mensajes en lugar de /mensajes/crear, ya que la acción ya se especifica mediante con la petición POST.
• La ruta usada para borrar un mensaje, debería ser /mensajes/2 en lugar de /mensajes/2/eliminar, puesto que la acción ya se debería especificar en el tipo de petición DELETE.
• La ruta que se usa para actualizar un mensaje, debería ser /mensajes/2 en lugar de /mensajes/2/actualizar, dado que la acción ya se especifica mediante el tipo de petición PUT o PATCH.

Una ruta nunca debería contener la extensión del archivo devuelto, con independencia de que devuelva un archivo JSON o XML. Por ejemplo, una ruta válida sería /mensajes, mientras que el uso de /mensajes.json está mal considerado.

Estas reglas son solamente recomendaciones y no normas estrictas, pero su uso son una buena práctica fácilmente reconocible por parte de los desarrolladores con más experiencia. El uso de estándares hace que una API sea más consistente, especialmente cuando varios desarrolladores trabajan en ella.

Herramientas de apoyo

Existen diferentes aplicaciones que puedes usar durante el desarrollo de una API. Por ejemplo, podrías usar Postman, que es un entorno de pruebas específicamente creado para el desarrollo de APIs. Además, también podrías usar aplicaciones de línea de comandos como cURL o aplicaciones web como ReqBin.

El comando curl seguido de los flags -i o --include enviarán una petición GET a la URL que especifiquemos, mostrando las cabeceras y el body de la respuesta cuando nos llegue de vuelta.

Por ejemplo, vamos a probar a usar cURL para obtener ciertos recursos. Para usar cURL, debes abrir una ventana de línea de comandos. Si usas Ubuntu o una distribución similar, puedes iniciar la terminal de varias formas. Si usas Windows, puedes usar la terminal de Linux en Windows.

Una vez hayas abierto una ventana de línea de comandos, usa este comando para enviar una petición GET a esta web:

curl -i https://www.neoguias.com

Deberías obtener de vuelta tanto el contenido de la página de inicio de esta web como las cabeceras:

HTTP/2 200
Date: Tue, 01 Dec 2020 11:00:24 GMT
Content-type: text/html; charset=UTF-8
Last-modified: Tue, 01 Dec 2020 10:30:30 GMT
Expires: Tue, 01 Dec 2020 11:30:30 GMT
Pragma: public
Cache-control: max-age=1806, public
Vary: Accept-Encoding
Referrer-policy: no-referrer-when-downgrade
...

Después de las cabeceras se mostrará el código HTML de la página.

Tal y como ves, se ha obtenido del código 200, indicando que la petición se ha procesado con éxito. Además, también se nos dice que se ha usado el protocolo HTTP/2.

La cabecera content-type tiene el valor text/html, indicándonos el tipo de contenido de la página, que en este caso es código HTML. Sin embargo, si realizas una petición a la siguiente URL, verás que el valor de la cabecera content-type es ahora application/json:

curl -i https://jsonplaceholder.typicode.com/users

Cuando creas una API REST, seguramente querrás responder con código JSON estructurado en lugar de devolver texto plano.

A continuación, introduce el siguiente comando:

curl -i http:/www.neoguias.com

En este caso, hemos usado el protocolo HTTP en lugar de usar el protocolo seguro HTTPS, por lo que el servidor ha hecho una redirección, a la versión HTTPS de la página. Si te fijas en la respuesta, verás que contiene lo siguiente:

HTTP/2 301 
Location: https://www.neoguias.com/ 
Content-type: text/html; 
Charset=UTF-8
...

Tal y como ves, se ha obtenido el código 301, ya que el servidor ha redireccionado la página a su correspondiente versión HTTPS.

Cómo crear una API REST

Mediante este artículo has aprendido lo que es una API REST, así como varios detalles acerca de su arquitectura e implementación. En próximos tutoriales veremos cómo puedes crear una API REST mediante diferentes lenguajes de programación, como JavaScript y PHP.

Esto ha sido todo.

---