Conceptos sobre APIs REST

En esta entrada voy a resumir los conceptos ms importantes que he tratado en mis
ponencias sobre REST.

Qu es REST?
REST, REpresentational State Transfer, es un tipo de arquitectura de desarrollo web que se
apoya totalmente en el estndar HTTP.
REST nos permite crear servicios y aplicaciones que pueden ser usadas por cualquier
dispositivo o cliente que entienda HTTP, por lo que es increblemente ms simple y
convencional que otras alternativas que se han usado en los ltimos diez aos como SOAP
y XML-RPC.
REST se defini en el 2000 por Roy Fielding, coautor principal tambin de la
especificacin HTTP. Podramos considerar REST como un framework para construir
aplicaciones web respetando HTTP.
Por lo tanto REST es el tipo de arquitectura ms natural y estndar para crear APIs para
servicios orientados a Internet.
Existen tres niveles de calidad a la hora de aplicar REST en el desarrollo de una aplicacin
web y ms concretamente una API que se recogen en un modelo llamado Richardson
Maturity Model en honor al tipo que lo estableci, Leonard Richardson padre de la
arquitectura orientada a recursos. Estos niveles son:
1. Uso correcto de URIs
2. Uso correcto de HTTP.
3. Implementar Hypermedia.
Adems de estas tres reglas, nunca se debe guardar estado en el servidor, toda la
informacin que se requiere para mostrar la informacin que se solicita debe estar en la
consulta por parte del cliente.
Al no guardar estado, REST nos da mucho juego, ya que podemos escalar mejor sin tener
que preocuparnos de temas como el almacenamiento de variables de sesin e incluso,
podemos jugar con distintas tecnologas para servir determinadas partes o recursos de una
misma API.

Nivel 1: Uso correcto de URIs

Cuando desarrollamos una web o una aplicacin web, las URLs nos permiten acceder a
cada uno de las pginas, secciones o documentos del sitio web.
Cada pgina, informacin en una seccin, archivo, cuando hablamos de REST, los
nombramos como recursos.
El recurso por lo tanto es la informacin a la que queremos acceder o que queremos
modificar o borrar, independientemente de su formato.
Las URL, Uniform Resource Locator , son un tipo de URI, Uniform Resource Identifier,
que adems de permitir identificar de forma nica el recurso, nos permite localizarlo para
poder acceder a l o compartir su ubicacin.
Una URL se estructura de la siguiente forma:
{protocolo}://{dominio o hostname}[:puerto (opcional)]/{ruta del
recurso}?{consulta de filtrado}

Por ejemplo, http://asiermarques.com/2013/conceptos-sobre-apis-rest/, sera la URL para

visualizar este artculo.
Existen varias reglas bsicas para ponerle nombre a la URI de un recurso:

Los nombres de URI no deben implicar una accin, por lo tanto debe evitarse usar
verbos en ellos.

Deben ser nicas, no debemos tener ms de una URI para identificar un mismo
recurso.

Deben ser independiente de formato.

Deben mantener una jerarqua lgica.

Los filtrados de informacin de un recurso no se hacen en la URI.

Las URIs no deben implicar acciones y deben ser nicas

Por ejemplo, la URI /facturas/234/editar sera incorrecta ya que tenemos el verbo editar en
la misma.
Para el recurso factura con el identificador 234, la siguiente URI sera la correcta,
independientemente de que vayamos a editarla, borrarla, consultarla o leer slo uno de de
sus conceptos: /facturas/234
Las URIs deben ser independientes de formato

Por ejemplo, la URI /facturas/234.pdf no sera una URI correcta, ya que estamos
indicando la extensin pdf en la misma.
Para el recurso factura con el identificador 234, la siguiente URI sera la correcta,
independientemente de que vayamos a consultarla en formato pdf, epub, txt, xml o
json: /facturas/234
Las URIs deben mantener una jerarqua lgica
Por ejemplo, la URI /facturas/234/cliente/007 no sera una URI correcta, ya que no sigue
una jerarqua lgica.
Para el recurso factura con el identificador 234 del cliente 007, la siguiente URI sera la
correcta: /clientes/007/facturas/234
Filtrados y otras operaciones.
Para filtrar, ordenar, paginar o buscar informacin en un recurso, debemos hacer una
consulta sobre la URI, utilizando parmetros HTTP en lugar de incluirlos en la misma.
Por ejemplo, la URI /facturas/orden/desc/fecha-desde/2007/pagina/2 sera incorrecta ya
que el recurso de listado de facturas sera el mismo pero utilizaramos una URI distinta para
filtrarlo, ordenarlo o paginarlo.
La URI correcta en este caso sera:
/facturas?fecha-desde=2007&orden=DESC&pagina=2

Nivel 2: HTTP
Conocer bien HTTP no es opcional para un desarrollador web al que le importe su trabajo.
Aunque el RFC es sencillo de leer, si ests interesado en aprender bien las bases de este
protocolo es muy recomendable la gua de OReilly sobre el mismo.
Para desarrollar APIs REST los aspectos claves que hay que dominar y tener claros son:

Mtodos HTTP

Cdigos de estado

Aceptacin de tipos de contenido

Mtodos.
Como hemos visto en el anterior nivel, a la hora de crear URIs no debemos poner verbos
que impliquen accin, aunque queramos manipular el recurso.

Para manipular los recursos, HTTP nos dota de los siguientes mtodos con los cuales
debemos operar:

GET: Para consultar y leer recursos

POST: Para crear recursos

PUT: Para editar recursos

DELETE: Para eliminar recursos.

PATCH: Para editar partes concretas de un recurso.

Por ejemplo para un recurso de facturas.

GET /facturas Nos permite acceder al listado de facturas
POST /facturas Nos permite crear una factura nueva
GET /facturas/123 Nos permite acceder al detalle de una factura
PUT /facturas/123 Nos permite editar la factura, sustituyendo la totalidad de la
informacin anterior por la nueva.
DELETE /facturas/123 Nos permite eliminar la factura
PATCH /facturas/123 Nos permite modificar cierta informacin de la factura, como el
nmero o la fecha de la misma.
Quiz debido al desconocimiento o el soporte de ciertos navegadores, los desarrolladores
web han usado, durante los ltimos aos, nicamente los mtodos GET Y POST para
realizar todas estas acciones. Si trabajamos con REST, esto sera un error de base y puede
darnos problemas incluso a la hora de nombrar nuestros recursos, obligndonos a poner
verbos en las URLs.
Cdigos de estado.
Uno de los errores ms frecuentes a la hora de construir una API suele ser el reinventar la
rueda creando nuestras propias herramientas en lugar de utilizar las que ya han sido
creadas, pensadas y testadas. La rueda ms reinventada en el desarrollo de APIs son los
cdigos de error y cdigos de estado.
Cuando realizamos una operacin, es vitar saber si dicha operacin se ha realizado con
xito o en caso contrario, por qu ha fallado.
Un error comn sera por ejemplo:

1
2
3
4
5
6
7
8
9
10
11
12
13

Peticin
========
PUT /facturas/123
Respuesta
=========
Status Code 200
Content:
{
success: false,
code:
734,
error:
"datos insuficientes"
}

En este ejemplo se devuelve un cdigo de estado 200, que significa que la peticin se ha
realizado correctamente, sin embargo, estamos devolviendo en el cuerpo de la respuesta un
error y no el recurso solicitado en la URL.
Este es un error comn que tiene varios inconvenientes:

No es REST ni es estndar.

El cliente que acceda a este API debe conocer el funcionamiento especial y cmo
tratar los errores de la misma, por lo que requiere un esfuerzo adicional importante
para trabajar con nosotros.

Tenemos que preocuparnos por mantener nuestros propios cdigos o mensajes de

error, con todo lo que eso supone.

HTTP tiene un abanico muy amplio que cubre todas las posibles indicaciones que vamos a
tener que aadir en nuestras respuestas cuando las operaciones han ido bien o mal.
Es imperativo conocerlos y saber cundo utilizarlos, independientemente de que desarrolles
siguiendo REST.
El siguiente ejemplo sera correcto de la siguiente forma:
1
2
3
4
5
6
7
8
9 {
10

Peticin
========
PUT /facturas/123
Respuesta
=========
Status Code 400
Content:
message: "se debe especificar un id de cliente para la factura"

11

Tipos y formatos de contenido.

Cuando hablamos sobre URLs, vimos tambin que no era correcto indicar el tipo de
formato de un recurso al cual queremos acceder o manipular.
HTTP nos permite especificar en qu formato queremos recibir el recurso, pudiendo indicar
varios en orden de preferencia, para ello utilizamos el header Accept.
Nuestra API devolver el recurso en el primer formato disponible y, de no poder mostrar el
recurso en ninguno de los formatos indicados por el cliente mediante el header Accept,
devolver el cdigo de estado HTTP 406.
En la respuesta, se devolver el header Content-Type, para que el cliente sepa qu formato
se devuelve, por ejemplo:
1
Peticin
2
========
3 GET /facturas/123
4 Accept: application/epub+zip , application/pdf, application/json
5
6
Respuesta
7
=========
8
Status Code 200
9
Content-Type: application/pdf

En este caso, el cliente solicita la factura en epub comprimido con ZIP y de no tenerlo, en
pdf o json por orden de preferencia. El servidor le devuelve finalmente la factura en pdf.

Nivel 3: Hypermedia.
A pesar de lo que nos pueda inducir a pensar el trmino retrofuturista Hypermedia, el
concepto y la finalidad que busca describir es bastante sencillo: conectar mediante
vnculos las aplicaciones clientes con las APIs, permitiendo a dichos clientes
despreocuparse por conocer de antemano del cmo acceder a los recursos.
Con Hypermedia bsicamente aadimos informacin extra al recurso sobre su conexin a
otros recursos relacionados con l.
Aqu tenemos un ejemplo:
1
2
3
4
5

<pedido>
<id>666</id>
<estado>Procesado</estado>
<links>
<link rel="factura">

6
7
8
9

http://example.com/api/pedido/666/factura
</link>
</links>
</pedido>

En este ejemplo vemos cmo indicar en un xml que representa un pedido, el enlace al
recurso de la factura relacionada con el mismo.
Sin embargo, necesitamos que el cliente que accede a nuestra API entienda que esa
informacin no es propia del recurso, sino que es informacin aadida que puede utilizar
para enlazar el pedido con la factura.
Para ello conseguir esto, debemos utilizar las cabeceras Accept y Content-Type, para que
tanto el cliente como la API, sepan que estn hablando hypermedia.
Por ejemplo:
1
Peticin
2
========
3 GET /pedido/666
4 Accept: application/nuestra_api+xml, text/xml
5
6
Respuesta
7
=========
8
Status Code: 200
9
Content-Type: application/nuestra_api+xml
10 Content:
11
12
<pedido>
13
<id>666</id>
14
<estado>Procesado</estado>
15
<links>
16
<link rel="factura">
17
http://example.com/api/pedido/666/factura
18
</link>
19
</links>
20
</pedido>

Como vemos, el cliente solicita el formato application/nuestra_api+xml de forma

preferente al formato text/xml. De esta forma, le indica al servicio web, que entiende su
formato hypermedia y puede aprovecharlo.
El servicio web por lo tanto, como implementa hypermedia, le devuelve la informacin de
recurso y la informacin de hypermedia que puede utilizar el cliente.
Hypermedia es til por ejemplo para que el cliente no tenga que conocer las URLs de los
recursos, evitando tener que hacer mantenimientos en cada uno de los mismos si en un

futuro dichas URLs cambian (cosa que no debera pasar). Tambin es til para automatizar
procesos entre APIs sin que haya interaccin humana.

Conclusin
Como hemos visto, los principios bsicos para construir APIs REST se basan en conocer
sobre todo HTTP, algo que no es opcional para un desarrollador web.