Las cosas que debes de saber sobre API REST

API REST (Representational State Transfer) no es un protocolo, sino unos principios de arquitectura, un estilo y unos patrones de diseño para la descripción de interfaces web. No hay unas normas completamente cerradas, sino una serie de guías que, si se siguen, permiten obtener interfaces o APIs RESTful. O RESTlike, si aplican las guías con algo de imaginación y flexibilidad cuando REST no encaja como un guante al API que se necesita implementar.

apirest

apirest

 

Los conceptos básicos de REST son los siguientes:

Lo principal son los recursos. Un recurso es igual a una URI. La URI indica donde está el recurso, por ejemplo un libro en una biblioteca:

http://mibiblioteca.com/biblioapi/v1/libros/libro1234

De forma general, una URI puede identificar a dos tipos de recursos:

Una colección o un recurso individual. Una colección es simplemente una agrupación de recursos del mismo tipo.

Las colecciones se deben nombrar en plural y con nombrados concretos. Además deben usarse nombres, puesto que el verbo lo define el método HTTP. Los recursos individuales tienen su propio identificador, que debe ser único dentro de la colección. Así, el identificador del recurso sirve como indexador en la colección.

Como hemos dicho, los métodos HTTP sirven para realizar operaciones sobre las colecciones y recursos. Los métodos HTTP nos permiten operaciones CRUD: Create, Retrieve, Update y Delete.

POST para Crear, GET para Obtener, PUT para actualizar y DELETE para borrar. Esto de forma básica, pero siempre hay matices: ¿qué ocurre si se intenta POST sobre un recurso que ya existe? ¿cómo puedo actualizar solo algunos atributos de un recurso? ¿y borrarlos? ¿debo permitir todas las combinaciones?

Analizando temas algo más avanzados, surgen aspectos como:

Manejo de errores, que es un tema fundamental para obtener un buen API. En REST lo fundamental es utilizar los códigos de error HTTP: 400 Bad Request si la petición es sintácticamente invalida, 401 Unauthorized para problemas de autenticación, 403 Forbidden para problemas de autorización o limitación por políticas, 404 Not Found si se intenta acceder a un recurso que no existe (o que se quiere ocultar), 5xx cuando hay algún problema en el servidor. Otros códigos se pueden usar, pero no es recomendable usar todos, sino aquellos cuyo uso está más extendido.

Para complementar al código HTTP es muy útil incluir un body HTTP con un formato definido que incluya por ejemplo el código del error (útil para la máquina), un texto descriptivo (para el humano) y una URL donde obtener más información del error. Por ejemplo:

HTTP 403 Forbidden

Content-Type: application/json

{ “errorId”: “SVC1000”,

“errorInfo”: “Falta parámetro obligatorio: autor”,

“masInfo”:

http://mibiblioteca.com/biblioapi/v1/utils/error/svc1000 }

Filtrados y búsquedas, útiles para obtener recursos de una colección que cumplan ciertos criterios y para obtener solo los atributos de los recursos que se requieran. Tanto los filtrados como las búsquedas, así como la paginación, se consiguen a través de query strings o query parameters. Hay diferentes formas de conseguirlo; las siguientes son formas sencillas y útiles:

Para obtener solo los atributos requeridos de un recurso, basta con incluir el query ?fields=param1,param2,param3. Para obtener solo los recursos que cumplan uno o varios criterios, basta con incluir el criterio como query: ?crit1=2&crit2=3,4.

Diferentes valores y criterios pueden combinarse para obtener lógica AND y OR. Para paginar, usando dos query parameters se puede hacer todo.

Con un parámetro offset se indica el desplazamiento en el listado de recursos y con un parámetro limit se indica el número máximo de resultados deseados. Un aspecto fundamental para el mantenimiento y evolución de un API es el versionado.

Existen muchas estrategias, pero una sencilla y recomendable es incluir el número de versión del API en la propia URL, justo después del nombre del API. Cuando se hagan cambios compatibles hacia atrás no se evoluciona la versión en la URL, solo cuando se haga un cambio que haga incompatible la nueva versión con la antigua. Existen métodos probablemente más ortodoxos y potentes como utilizar las cabeceras HTTP para señalizar la versión del recurso y las versiones soportadas.

Estos métodos también son más complicados, y en un API REST la sencillez y usabilidad es pieza clave.

Otro aspecto interesante es, ¿cómo indicar la URL de un recurso cuando éste es creado? Dos son las principales técnicas: una es incluir una cabecera HTTP Location en la respuesta a la petición de creación del recurso. En la cabecera se incluye la URL donde se ha creado el recurso. Otra es incluir en la respuesta la representación del recurso creado, que incluirá entre sus atributos el identificador del recurso. O, de forma alternativa, devolver solo el identificador del recurso en vez de su representación completa.

Una práctica recomendable es incluir tanto la cabecera Location como el identificador del recurso en el body HTTP; así se consigue de forma sencilla una solución válida para distintos clientes, los que quieran hacer uso de cabeceras HTTP y los que no.

Formatos y representaciones. El formato que mejor encaja en un API REST es JSON8, así que en general elígelo como formato de representación de tus recursos. También puedes hacer un API REST representando los recursos en XML9, y puedes asociar un esquema que defina el XML para definir el tipo de tus recursos y sus atributos.

Es posible que quieras ofrecer ambas representaciones, en cuyo caso tienes que tener unas reglas claras para la transformación entre formatos, lo cual puede no ser obvio salvo que fijes algunas reglas como no usar atributos en XML.

Por último, usar URLs sencillas y entendibles es fundamental. Recopilando los conceptos tratados en puntos anteriores, se obtiene el siguiente esquema:

https://host:puerto/nombre/{version}/coleccion/{Id}? queries o nombre: sitúa aquí el nombre del API. o {version}: variable para indicar la versión del API, con las normas comentadas anteriormente.