Está en la página 1de 5

Capítulo 8.

Mejores prácticas de REST y


ROA
Por ahora debe tener una buena idea de cómo crear servicios web RESTful
orientados a recursos. Este capítulo es una pausa para reunir en un solo lugar
las ideas más importantes hasta el momento, y para llenar algunas de las
lagunas en mi cobertura.

Las lagunas existen porque los capítulos teóricos se han centrado en lo básico, y
los capítulos prácticos han funcionado con servicios específicos. Implementé
HTTP condicional GET pero no lo he explicado. Implementé la autenticación
HTTP básica y un cliente para el mecanismo de autenticación personalizado de
Amazon, pero no los comparé con otros tipos de autenticación HTTP, y pasé por
alto el problema de autenticar un cliente para su propio usuario .

La primera parte de este capítulo es un resumen de las ideas principales de


REST y el ROA. La segunda parte describe las ideas que aún no he
cubierto. Hablo sobre características específicas de HTTP y casos difíciles en el
diseño de recursos. En el Capítulo 9 , analizo los componentes básicos de los
servicios: tecnologías y patrones específicos que se han utilizado para crear
servicios web exitosos. En conjunto, este capítulo y el siguiente forman una
referencia práctica para los servicios web RESTful. Puede consultarlos cuando
sea necesario al tomar decisiones de tecnología o diseño.

Conceptos básicos orientados a los recursos


Lo únicolas diferencias entre un servicio web y un sitio web son la audiencia
(clientes preprogramados en lugar de seres humanos) y algunas capacidades del
cliente. Tanto los servicios web como los sitios web se benefician de un diseño
orientado a recursos basado en HTTP, URI y (generalmente) XML.

Cada cosa interesante que maneja su aplicación debe estar expuesta


como un recurso . Un recurso puede ser cualquier cosa que un cliente desee
vincular: una obra de arte, una pieza de información, un objeto físico, un
concepto o una agrupación de referencias a otros recursos.
Un URI es el nombre de un recurso. Cada recurso debe tener al menos un
nombre. Un recurso debe tener el menor número posible de nombres, y cada
nombre debe ser significativo.

El cliente no puede acceder a los recursos directamente. Un servicio web


sirverepresentaciones de un recurso: documentos en formatos de datos
específicos que contienen información sobre el recurso. La diferencia entre un
recurso y su representación es algo académica para los sitios web estáticos,
donde los recursos son solo archivos en el disco que se envían literalmente a los
clientes. La distinción adquiere mayor importancia cuando el recurso es una fila
en una base de datos, un objeto físico, un concepto abstracto o un evento real en
progreso.

Todo el acceso a los recursos ocurre a través de la interfaz uniforme de


HTTP. Estos son los cuatro verbos HTTP básicos (GET, POST, PUT y DELETE)
y los dos auxiliares (HEAD y OPTIONS). Ponga la complejidad en sus
representaciones, en la variedad de recursos que expone y en los enlaces entre
los recursos. No lo pongas en los métodos de acceso.

El procedimiento Generic ROA


Reimpresodel Capítulo 6 , este es un procedimiento multiusos para dividir un
espacio problemático en recursos REST.

Este procedimiento solo tiene en cuenta las restricciones de REST y el ROA. Su


elección de marco puede imponer restricciones adicionales. Si es así, también
debería tenerlos en cuenta mientras diseña los recursos. En el Capítulo 12 doy
una versión modificada de este procedimiento que funciona con Ruby on Rails.

1. Averiguar el conjunto de datos


2. Divida el conjunto de datos en recursos

Para cada tipo de recurso:

3. Nombra los recursos con URI


4. Exponer un subconjunto de la interfaz uniforme
5. Diseñar la (s) representación (es) aceptada (s) del cliente
6. Diseña la (s) representación (es) servida (s) al cliente
7. Integre este recurso en los recursos existentes, utilizando enlaces y
formularios hipermedia
8. Considere el curso típico de eventos: ¿qué se supone que sucederá? Los
flujos de control estándar como el Protocolo de publicación Atom pueden
ayudar (consulte el Capítulo 9 ).
9. Considere las condiciones de error: ¿qué podría salir mal? De nuevo, los
flujos de control estándar pueden ayudar.

Direccionabilidad
Un servicio webes direccionable si expone los aspectos interesantes de su
conjunto de datos a través de los recursos. Cada recurso tiene su propio y
únicoURI: de hecho, URI solo significa "Identificador Universal de Recursos".
La mayoría de los servicios web RESTful exponen una cantidad infinita de
URI. La mayoría de los servicios web de estilo RPC exponen muy pocos URI, a
menudo tan solo uno.

Las representaciones deben ser direccionables


Un URI nunca debe representar más de un recurso. Entonces no sería
un Identificador Universal de Recursos. Además, sugiero
quecada representaciónde un recurso debe tener su propio URI. Esto se debe a
que los URI a menudo se pasan o se usan como entrada para otros servicios
web. La expectativa es que el URI designe una representación particular del
recurso.

Digamos que has expuesto un comunicado de prensa en /releases/104. Hay


una versión en inglés y en español del comunicado de prensa, una versión en
HTML y texto sin formato de cada uno. Sus clientes deberían poder configurar
el Accept-Languageencabezado de la solicitud para elegir una representación en
inglés o español /releases/104, y el Acceptencabezado de la solicitud para
elegir una representación HTML o de texto sin formato. Pero también se debe
dar a cada representación un URI separado: tal vez como
URIs /releases/104.en, /releases/104.es.htmly /releases/104.txt.
En el servicio de marcado del Capítulo 7 , expuse dos representaciones de un
conjunto de marcadores: una representación XML genérica
en /v1/users/leonardr/bookmarks.xml, y una representación de Atom
en /v1/users/leonardr/bookmarks.atom. También expuse un URI canónico
para el recurso en /v1/users/leonardr/bookmarks. Un cliente puede establecer
su Acceptencabezado de solicitud para distinguir entre Atom y las
representaciones XML genéricas de /v1/users/leonardr/bookmarks, o puede
ajustar el URI para obtener una representación diferente. Ambas técnicas
funcionan, y ambas técnicas son RESTful, pero un URI viaja mejor entre los
clientes si especifica un recurso y una representación.

Está bien que un cliente envíe información en encabezados de solicitud HTTP,


siempre y cuando el servidor no lo haga la única forma de seleccionar un
recurso o representación. Los encabezados también pueden contener
información confidencial, como credenciales de autenticación, o información
diferente para cada cliente. Pero los encabezados no deben ser la única
herramienta que un cliente tiene para especificar qué representación se sirve o
qué recurso se selecciona.

Estado y apatridia
Ahíson dos tipos de estado en un servicio RESTful. Hay estado del recurso, que
es información sobre recursos y estado de la aplicación, que es información
sobre la ruta que el cliente ha tomado a través de la aplicación. El estado del
recurso permanece en el servidor y solo se envía al cliente en forma de
representaciones. El estado de la aplicación permanece en el cliente hasta que se
pueda usar para crear, modificar o eliminar un recurso. Luego se envía al
servidor como parte de una solicitud POST, PUT o DELETE, y se convierte en
estado de recursos.

Un servicio RESTful es "sin estado" si el servidor nunca almacena ningúnestado


de aplicación. En una aplicación sin estado, el servidor considera cada solicitud
de cliente de forma aislada y en términos del estado de recursos actual. Si el
cliente quiere que se tenga en cuenta un estado de aplicación, el cliente debe
enviarlo como parte de la solicitud. Esto incluye cosas como las credenciales de
autenticación, que se envían con cada solicitud.
El cliente manipula el estado del recurso enviando una representación como
parte de una solicitud PUT o POST. (Las solicitudes DELETE funcionan de la
misma manera, pero no hay representación.) El servidor manipula el estado del
cliente enviando representaciones en respuesta a las solicitudes GET del
cliente. Aquí es donde el nombre "Transferencia de estado representacional"
proviene de.