PDF de programación - Principios de diseño de APIs REST

Principios de diseño de APIs REST
(desmitificando REST)

Enrique Amodeo

This book is for sale at http://leanpub.com/introduccion_apis_rest

This version was published on 2013-03-06

This is a Leanpub book. Leanpub empowers authors and publishers with the Lean Publishing
process. Lean Publishing is the act of publishing an in-progress ebook using lightweight tools and
many iterations to get reader feedback, pivot until you have the right book and build traction once
you do.

©2012 - 2013 Enrique Amodeo

Tweet This Book!

Please help Enrique Amodeo by spreading the word about this book on Twitter!

The suggested tweet for this book is:

Acabo de comprar ”Principios de Diseño de APIs REST” El libro de #REST en español #esrest

The suggested hashtag for this book is #esrest.

Find out what other people are saying about the book by clicking on this link to search for this
hashtag on Twitter:

https://twitter.com/search/#esrest

Índice general

Sobre la cubierta

Agradecimientos

Érase una vez…

1 APIs orientadas a datos: CRUD
.
.
.
.
.

.
.
.
.
.
Seguramente CRUD no sea lo mejor para tu API… .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.

.

Introducción .
1.1
1.2
.
Leyendo .
1.3 Actualizando .
1.4
.
1.5 Creando .
.
1.6

Borrando .
.

.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

i

ii

iii

1
1
2
9
11
12
15

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

Sobre la cubierta

La foto de la cubierta es de un famoso trampantojo en la ciudad de Quebec, más concretamente en
el Quartier Petit Champlain.
El autor eligió esta foto como cubierta porque ilustra claramente un conjunto de agentes interope-
rando entre sí.

i

Agradecimientos

Este libro empezó como un pequeño y corto capítulo en otro libro. Los que me conocen ya se temían
que ese pequeño capítulo no iba a ser tan pequeño. Debido a ello, y a problemas de calendario decidí
publicar el libro por separado y a mi ritmo. Gracias a ese equipo de personas por poner en marcha
esto y por sus sugerencias, en especial a @ydarias, @estebanm, y @carlosble.
Gracias a todos aquellos que me han ayudado a mover el libro por el mundo del “social media”.
Me gustaría agradecer a @pasku1 y a @juergas por sus esfuerzos como revisores de este libro (os
debo una caña… bueno dos). Sé que siempre puedo recurrir a ellos cuando me apetece calentarle la
cabeza a alguien con mi última idea.
Y como no podría ser de otra forma, un agradecimiento especial a mi mujer, @mcberros, por no
permitir nunca que dejara este proyecto y por su apoyo incondicional.

ii

Érase una vez…

Tras muchos años intentando crear servicios web basados en tecnologías RPC, tales como CORBA
o SOAP, la industria del desarrollo de software se encontraba en un punto muerto. Cierto, se había
conseguido el gran logro de que un servicio implementado en .NET consiguiera comunicarse con
uno escrito en Java, o incluso con otro hecho a base de COBOL, sin embargo todo esto sabía a
poco. Es normal que supiera a poco, se había invertido cantidades ingentes de dinero en distintas
tecnologías, frameworks y herramientas, y las recompensas eran escasas. Lo peor es que además las
compañías se encontraban encalladas en varios problemas.
Por un lado la mantenibilidad de la base de código resultante era bastante baja. Se necesitaban
complejos IDEs para generar las inescrutables toneladas de código necesarias para interoperar.
Los desarrolladores tenían pesadillas con la posibilidad de que se descubriera algún bug en la
herramienta de turno, o de que algún parche en éstas destruyera la interoperabilidad. Y si se
necesitaba alguna versión o capacidad más avanzada de SOAP, probablemente el IDE no lo soportara
o tuviera que ser actualizado.
Por otro lado, para depurar cualquier problema de interoperabilidad, había que bajar al nivel de
HTTP: ¿estarían las cabeceras apropiadas? ¿La serialización del documento SOAP es conforme a
“Basic Profile”¹? ¿No se suponía que SOAP nos desacoplaba totalmente del protocolo de transporte?
Finalmente también había descontento. Se había soñado con un mundo de servicios web interope-
rables de manera transparente, organizados en directorios UDDI, con transacciones distribuidas a
través de internet, etc. Al final esto no se consiguió, sólo interoperaban servicios entre distintos
departamentos de una misma empresa, o de forma más rara algún servicio llamaba a otro servicio
de otra empresa, todo con mucho cuidado y en condiciones bastante frágiles.
Cuando la situación se hizo insostenible, y algunos gigantes de la informática como Amazon, Google
o Twitter necesitaron interoperabilidad a escala global y barata, alguien descubrió el camino al futuro
mirando hacia el pasado, y descubrió REST…

¹http://www.ws-i.org/profiles/BasicProfile-1.0-2004-04-16.html

iii

1 APIs orientadas a datos: CRUD
1.1 Introducción

El caso de uso más sencillo al diseñar servicios REST con HTTP se produce cuando dichos servicios
publican operaciones CRUD sobre nuestra capa de acceso a datos. El acrónimo CRUD responde
a “Create Read Update Delete” y se usa para referirse a operaciones e mantenimiento de datos,
normalmente sobre tablas de un gestor relacional de base de datos. En este estilo de diseño existen
dos tipos de recursos: entidades y colecciones.
Las colecciones actuan como listas o contenedores de entidades, y en el caso puramente CRUD se
suelen corresponder con tablas de base de datos. Normalmente su URI se deriva del nombre de la
entidad que contienen. Por ejemplo, http://www.server.com/rest/libro sería una buena URI para
la colección de todos los libros dentro de un sistema. Para cada colección se suele usar el siguiente
mapeo de métodos HTTP a operaciones:

Método HTTP Operación

GET
PUT

DELETE
POST

Leer todas las entidades dentro de la colección
Actualización mútiple y/o masiva
Borrar la colección y todas sus entidades
Crear una nueva entidad dentro de la colección

Las entidades son ocurrencias o instancias concretas, que viven dentro de una colección. La
URI de una entidad se suele modelar concatenado a la URI de la colección correspondiente un
identificador de entidad. Este identificador sólo necesita ser único dentro de dicha colección. Ej.
http://www.server.com/rest/libro/ASV2-4fw-3 sería el libro cuyo identificador es ASV2-4fw-3.
Normalmente se suele usar la siguiente convención a la hora de mapear métodos HTTP a operaciones
cuando se trabaja con entidades.

Método HTTP Operación

GET
PUT

DELETE
POST

Leer los datos de una entidad en concreto
Actualizar una entidad existente o crearla si no existe
Borrar una entidad en concreto
Añadir información a una entidad ya existente

A continuación, en las siguientes secciones, veremos más en detalle algunas opciones de diseño para
cada operación CRUD.

1

APIs orientadas a datos: CRUD

1.2 Leyendo

2

La operación que parece más sencilla de modelar es la de lectura, aunque como veremos, el demonio
está en los detalles.
Todas las operaciones de lectura y consulta deben hacerse con el método GET, ya que según la
especificación HTTP, indica la operación de recuperar información del servidor.

Lectura de entidades

El caso más sencillo es el de leer la información de una entidad, que se realiza haciendo un GET contra
la URI de la entidad. Esto no tiene mucho más misterio, salvo en el caso de que el volumen de datos
de la entidad sea muy alto. En estos casos es común que queramos recuperar los datos de la entidad
pero sólo para consultar una parte de la información y no toda, con lo que estamos descargando
mucha información que no nos es útil.
Una posible solución es dejar sólo en esa entidad los datos de uso más común, y el resto dividirlo
en varios recursos hijos. De esta manera cuando el cliente lea la entidad, sólo recibirá los datos de
uso más común y un conjunto de enlaces a los recursos hijos, que contienen los diferentes detalles
asociados a ésta. Cada recurso hijo puede ser a su vez o una entidad o una colección.
En general se suele seguir la convención de concatenar el nombre del detalle a la URI de la entidad pa-
dre para conseguir la URI de la entidad hija. Por ejemplo, dada una entidad /rest/libro/23424-dsdff,
si se le realiza un GET, recibiríamos un documento, con el título, los autores, un resumen, valoración
global, una lista de enlaces a los distintos capítulos, otra para los comentarios y valoraciones, etc.
Una opción de diseño es hacer que todos los libros tengan una colección de capítulos como
recurso hijo. Para acceder al capítulo 3, podríamos modelar los capítulos como una colección y
tener la siguiente URL: /rest/libro/23424-dsdff/capitulo/3. Con este diseño tenemos a nuestra
disposición una colección en /rest/libro/23424-dsdff/capitulo, con la cual podemos operar de
forma estándar, para insertar, actualizar, borrar o consultar capítulos. Este diseño es bastante flexible
y potente.
Otro diseño, más simple, sería no tener esa colección intermedia y hacer que cada capítulo
fuera un recurso que colgara directamente del libro, con lo que la URI del capítulo 3 sería:
/rest/libro/23424-dsdff/capitulo3. Este diseño es más simple y directo y no nos ofrece la
flexibilidad del anterior.

¿Cuál es la mejor opción? Depende del caso de uso que tengamos para nuestra
API.
Si no tenemos claro que operación vamos a soportar para las entidades hijas, o
si sabemos que necesitamos añadir, borrar y consultar por diversos criterios, es
mejor usar una colección intermedia.

..

APIs orientadas a datos: CRUD

3

Si no necesitamos todo esto, es mejor hacer enlaces directos, ya que es un diseño
más sencillo.

..

Volviendo al problema de tener una entidad con un gran volumen de datos, existe otra solución en
la que no es necesario descomponerla en varios recursos. Se trata simpl