Buenas prácticas con servicios REST

En esta sección vamos a comentar una serie de buenas prácticas a llevar a cabo para que nuestros servicios web estén bien diseñados, lo que nos permitirá reducir los costes de mantenimiento y gestionar de manera más eficiente todas las operaciones.

Éstas son recomendaciones de buen uso ya que no hay un estándar que permita ajustarnos a unas reglas, por lo tanto se deben seguir de manera razonable, siempre y cuando no suponga desvirtuar nuestra api.

Como hemos visto en la sección Comenzando con los servicios REST: ¿qué es un servicio REST? los servicios REST se basan en recursos sobre los cuales podemos actuar usando los “verbos”: GET, POST, PUT, DELETE. Con esta premisa en mente debemos diseñar nuestra api REST y sus diferentes funcionalidades.

A continuación vamos a mencionar los principios básicos a la hora de construir nuestros servicios REST.

Como hemos visto con anterioridad, los servicios REST se basan en recursos, por lo tanto en nuestra url, a la hora de especificar el método al que llamar deberemos hacerlo con el nombre del recurso (en plural) en vez de un verbo que indique una acción.

Con la nomenclatura por nombres y haciendo uso de las peticiones GET, POST, PUT y DELETE podremos llevar a cabo nuestra funcionalidad de manera estándar.

No debemos usar verbos como, para el caso anterior:

/getAllCars       -> Listar coches
/createNewCar     -> Crear coche
/deleteAllRedCars ->Borrar coches rojos

No obstante en el caso de que una determinada acción no vaya asociada directamente a un recurso, sí que deberemos utilizar verbos para especificar la acción a realizar por el backend. Un ejemplo de esto sería la realización de un login.

Para modificar un recurso ya disponemos de los verbos POST, PUT y DELETE. No obstante en ocasiones cuando lo que queremos es hacer un cambio pequeño, como pasar un objeto de habilitado a deshabilitado, podemos estar tentados de hacer la petición GET correspondiente con un parámetro para activar o desactivar.

Esta manera de proceder no es correcta, ya que el método GET tiene como única misión acceder al recurso pero sin cambiarle el estado.

GET /alumnos/711?activo <-- Incorrecto
GET /alumnos/711/activo <-- Incorrecto

Debemos usar siempre el plural a la hora de referirnos a los recursos y asegurarnos que en toda nuestra api es así.

Si tenemos dos entidades, asignaturas y alumnos, y ambas están relacionadas, para hacer una consulta sobre ellas debemos usar los subrecursos. Es decir, dada la siguiente url:

GET /asignaturas/711/alumnos/

Llamamos subrecurso a un recurso dentro de otro, es decir “alumnos” sería un subrecurso de “asignaturas”.

El uso de los subrecursos es para identificar relaciones en la url y mantener el enfoque basado a recursos de REST.

GET /asignaturas/711/listaAlumnos/ <-- Incorrecto

A la hora de diseñar nuestra API rest es recomendable separar la parte de la API que requiere autenticación de la parte de la API que es pública y accesible por cualquier usuario.

Para ello podemos definir dos puntos de acceso a nuestra API uno “public” y otro “private”

GET ..public/asignaturas/711/   <-- Consulta
POST ..private/asignaturas/711  <-- Modificacion

Para mantener el desarrollo continuo independiente del mantenimiento es recomendable que versionemos nuestra API. Este pequeño cambio nos da una gran flexibilidad si tenemos que realizar una API paralela que modifica comportamientos de la ya existente.

En este caso podemos mantener ambas API por retrocompatibilidad, o mantener la antigua un tiempo hasta que decidamos darla de baja.

Para versionar nuestra API es suficiente con poner v1.0, v1.1,v2.0 etc dentro de la URL para separar las diferentes versiones de la misma.

 ../doctorados/v1.0/trabajos
 ../doctorados/v2.0/trabajos 

A continuación se muestran dos ejemplos completos de endpoints que reúnen todas las recomendaciones propuestas:

Ejemplo endpoint completo público:

https://miaplicacion.um.es/miaplicacion/rest/v1.0/public/recurso/subrecurso

Ejemplos endpoint completo privado:

    
https://miaplicacion.um.es/miaplicacion/rest/v1.0/private/recurso/subrecurso

Como se ha mencionado anteriormente, recurso y subrecurso son los objetos de la lógica de nuestra aplicación y deben referenciarse siempre en plural (p.ej. alumnos, asignaturas, artículos, etc…).

Pese a que usar los parámetros de cabecera no garantiza ninguna seguridad en la comunicación, es recomendable usarlos para intercambiar el usuario, contraseña y token de sesión entre dispositivos.

Para mejorar la gestión de nuestra API, es necesario usar los códigos HTTP estándar ya que garantizan una homogeneidad en el tratamiento de las respuestas.

Junto con estos códigos podemos enriquecer la respuesta con un mensaje mas detallado, pero es muy importante el uso de los mismos ya que cualquier navegador es capaz de entenderlos y procesarlos.

Dentro de todos los códigos que podemos utilizar, destacaremos 9 ya que son los más comunes:

• 200 – OK – Petición correcta
• 201 – OK – Recurso creado correctamente
• 204 – OK – Recurso eliminado correctamente
• 304 – Not Modified – El cliente puede usar la caché
• 400 – Bad Request – La petición es incorrecta o no se pudo atender. Normalmente en el payload de esta respuesta viene una descripción más detallada de lo ocurrido.
• 401 – Unauthorized – La petición requiere que el usuario se autentique.
• 403 – Forbidden – El acceso al recurso está restringido.
• 404 – Not found – No se encuentra el recurso
• 500 – Internal Server Error – Un error ha ocurrido en la parte del servidor.

Puede encontrar más información sobre el manejo de errores y sus buenas prácticas en la siguiente wiki: Manejo de errores en servicios REST