¿Qué es una API REST?

API REST: desde hace ya tiempo, se escucha mucho hablar sobre APIs de comunicación estilo REST y, de hecho, están muy extendidas en los sistemas que utilizamos diariamente. Pero, primero, ¿qué significa exactamente REST?

¿Qué significa REST?

«REST»: REpresentational State Transfer, es un tipo de arquitectura de desarrollo web que se apoya totalmente en el estándar HTTP. Fue definida en el 2000 por Roy Fielding, uno de los padres de la especificación HTTP y un referente en la arquitectura de redes.

Hoy por hoy, la mayoría de las aplicaciones que se desarrollan para servicios profesionales disponen de una API REST para el intercambio de información entre el front y el back. Lo que la hace tan potente es precisamente el aislamiento que proporciona entre la lógica del back-end y cualquier cliente consumidor de éste. Esto le permite ser usada por cualquier tipo de cliente: web, móvil, etc. Así, cualquier dispositivo/cliente que entienda de HTTP puede hacer uso de su propia API REST de manera muy simple. Esto ha hecho que en los últimos años este tipo de arquitectura haya ganado peso frente a otras más complejas como SOAP, para el intercambio y manipulación de datos.

Principales características de una API REST

Los objetos REST son manipulados a través de una URI (Uniform Resource Identifier)

Esta URI (endpoint) hace de identificador único de cada recurso del sistema REST, por lo que no puede ser compartida por más de un recurso. La estructura básica de una URI es la siguiente:

{protocolo}://{hostname}:{puerto}/{ruta del recurso}?{parámetros de filtrado (opcional)}

El nombre de la URI no debe contener palabras que impliquen acciones, por lo que deben evitarse los verbos en su construcción. Además, las URI siguen una jerarquía lógica de capas que permite ordenar los recursos y englobar las distintas funcionalidades entre sí. 

O bien agregando un cuerpo a la llamada REST en cualquier tipo de formato, siendo los más usados JSON y XML.

{
"order-by-clause" : "category desc",
"pageSize": 10,
"query-params":[
{
"cond-column": "apps",
"cond-operator":"IN",
"cond-values": [“Desarrollo” , “Salud”]
}]
}

Uso de la especificación HTTP

Para el desarrollo de una API REST es necesario un conocimiento profundo de la especificación HTTP, sobre todo en lo referente a métodos permitidos, códigos de estado y aceptación de tipos de contenido.

Los métodos son usados para manipular los diferentes recursos que conforman la API. Los principales métodos soportados por HTTP y por ello usados por una API REST son:

• POST: crear un recurso nuevo.
• PUT: modificar un recurso existente.
• GET: consultar información de un recurso.
• DELETE: eliminar un recurso determinado.
• PATCH: modificar solamente un atributo de un recurso.

Estos métodos junto con la URI, nos proporciona una interfaz uniforme que nos permite la transferencia de datos en el sistema REST aplicando operaciones concretas sobre un recurso determinado. Aunque la mayoría de las operaciones que componen una API REST podrían llevarse a cabo mediante métodos GET y POST, el abuso de ellos para operaciones que nada tienen que ver con el propósito con el que se concibieron, puede provocar un mal uso del protocolo alejado del estándar o la construcción de URIs con nomenclatura errónea mediante el uso de verbos.

Cuando se realiza una petición determinada, es de vital importancia conocer si dicha operación se ha llevado a cabo de manera satisfactoria o por el contrario se ha producido algún tipo de error. Para ello, HTTP dispone de un amplio número de códigos de error/éxito (https://es.wikipedia.org/wiki/Anexo:C%C3%B3digos_de_estado_HTTP) que cubren todas las posibles respuestas que el usuario puede recibir cuando trata de manipular un recurso mediante el uso de una API REST.

Las más comunes son:

• 200 OK. Respuesta estándar para peticiones correctas.
• 201 Created. La petición ha sido completada y ha resultado en la creación de un nuevo recurso.
• 202 Accepted. La petición ha sido aceptada para procesamiento, pero este no ha sido completado.
• 400 Bad Request. La solicitud contiene sintaxis errónea.
• 403 Forbidden. La solicitud fue legal, pero el servidor rehúsa responder dado que el cliente no tiene los privilegios para hacerla.
• 404 Not Found. Recurso no encontrado. Se utiliza cuando el servidor web no encuentra la página o recurso solicitado.
• 500 Internal Server Error. Es un código comúnmente emitido por aplicaciones empotradas en servidores web, cuando se encuentran con situaciones de error ajenas a la naturaleza del servidor web.

Ejemplo completo de la ejecución de una petición REST 

A continuación se muestra un ejemplo completo de la ejecución de una petición REST mediante una URI con parámetros de entrada y un cuerpo para el filtrado de datos. Como puede observarse también obtenemos el resultado de la consulta en formato JSON. La petición ha sido llevada a cabo de manera satisfactoria, por lo que recibimos un código “200 OK”.

HTTP además nos permite especificar en qué formato queremos recibir el recurso, pudiendo indicar varios en orden de preferencia, para ello utilizamos el header Accept.

GET: http://tech.tribalyte.eu/category/apps?pageSize=10&page=1

Accept: application/pdf, application/json

Nuestra API REST devolverá el recurso en el primer formato disponible y, de no poder mostrar el recurso en ninguno de los formatos indicados por el cliente, devolverá el código de estado HTTP 406 Not Acceptable (el servidor no es capaz de devolver los datos en ninguno de los formatos aceptados por el cliente, indicados por éste en la cabecera «Accept» de la petición).

En caso de respuesta satisfactoria, se devolverá el header Content-Type, para que el usuario sepa qué formato se devuelve, por ejemplo:

STATUS CODE 200.
Content-Type: application/pdf

Protocolo cliente/servidor sin estado

Cada petición HTTP contiene toda la información necesaria para ejecutarla, lo que permite que ni cliente ni servidor necesiten recordar ningún estado previo para satisfacerla. Aunque esto es así, algunas aplicaciones HTTP incorporan memoria caché. Se configura lo que se conoce como protocolo cliente-caché-servidor sin estado: existe la posibilidad de definir algunas respuestas a peticiones HTTP concretas como cacheables, con el objetivo de que el cliente pueda ejecutar en un futuro la misma respuesta para peticiones idénticas.

Uso de recursos Hypermedia

Haciendo uso de hipermedios se le permite al cliente consumidor de una API REST acceder de manera fácil a la navegación entre recursos, así como conectar unos recursos con otros que guardan algún tipo de relación entre sí. Este intercambio de vínculos mediante el uso de hipermedios tiene sus cimientos en el principio de HATEOAS (Hypermedia As The Engine Of Application State – Hipermedia Como Motor del Estado de la Aplicación). Este principio permite que cada vez que se hace una petición al servidor, parte de la respuesta que éste devuelve, debe contener información sobre vínculos relacionados con el recurso que se está consultando. Esto permite la navegación entre recursos.

{
"empresa": "Tribalyte",
"area": "Technologies",
"categories":
[
"category": "http://tech.tribalyte.eu/category/apps",
"category": "http://tech.tribalyte.eu/category/desarrollo-de-software",
"category": "http://tech.tribalyte.eu/category/salud",
]
}

¿Cuál es la principal ventaja de una API REST?

La principal ventaja del uso de una API REST reside en la independencia que proporciona frente a cualquier consumidor, sin importar el lenguaje o plataforma con el que se acceda a ella. Esto permite que una misma API REST sea consumida por infinidad de clientes sea cual sea la naturaleza de estos y que el cambio a cualquier otro tipo de consumidor no provoque impacto alguno en ella. Esta característica proporciona fiabilidad, escalabilidad y una fácil portabilidad a cualquier otra plataforma, ya que aisla por completo al cliente del servidor. Sólo se requiere que el intercambio de información de las respuestas se haga en un formato soportado, por lo general JSON o XML. Dicha separación entre el cliente y el servidor hace que se pueda migrar a otros servidores o bases de datos de manera transparente, siempre y cuando los datos se sigan enviado de manera correcta. Esto convierte a las APIs REST en una de las arquitecturas web más utilizadas  por la flexibilidad que aportan a cualquier entorno de trabajo sea cual sea su naturaleza.