Mejores prácticas para mejorar los web services de RESTful

Mejores prácticas para mejorar los web services de RESTful

Actualmente el uso de los servicios web de REST es esencial en el desarrollo de aplicaciones web y creación de APIs, entre otros. Uno de los errores que comúnmente vemos al diseñar este tipo de aplicaciones es que el desarrollador desconoce las mejores prácticas que deben seguirse, como consecuencia, la aplicación resulta desordenada, difícil de entender y utilizar.

En este post mencionaremos algunas de las mejores prácticas utilizadas para crear servicios web REST.

Para ser siempre stateless:

La primera regla en la gestión de los servicios web de REST es diseñar 100% stateless, lo que significa que cada solicitud realizada por algún cliente debe ser independiente de la anterior.

Los servicios web stateless permiten que la aplicación sea fácilmente escalable, evitando la migración de las sesiones de usuario de un clúster a otro, sólo necesitas poner un load balancer y una nueva instancia de la aplicación, así aseguras que cada solicitud será procesada (siempre y cuando sea una solicitud correcta).

Usa sustantivos, no verbos:

Lo que no debes hacer:

Método: GET    Endpoint: /getUsers/

Descripción: Devuelve una lista de usuarios.

Usa siempre nombres en lugar de verbos, cuando un desarrollador utiliza verbos el Endpoint, éste se vuelve redundante porque anteriormente ya está definido en el método HTTP.

La forma correcta de definir el endpoint anterior es la siguiente:

Método: GET    Endpoint: /users/

Descripción: Devuelve una lista de usuarios.

Este ejemplo está utilizando un Method HTTP GET y el endpoint /users/ que suena lógico y su propósito es fácil de entender.

Si necesitas obtener sólo un usuario, la forma correcta de manejar esto es la siguiente:

Método: GET    Endpoint: /users/123

Descripción: Devuelve un usuario con el ID especificado.

Como puedes ver, no hay necesidad de verbos ya que el endpoint /users/{id} es fácil de entender.

Algunos ejemplos de errores comunes son:

/getUsers           /updateUser     /deleteUser

Utilizar el método HTTP correcto

Un error común en muchas APIs REST es que la mayoría de sus servicios web son generalmente GET y POST. Aquí tienes una lista de los métodos HTTP disponibles, su uso y algunas respuestas comunes:

GET: Devuelve uno o varios recursos de acuerdo con la solicitud de salida, la respuesta más común es un JSON con el objeto u objetos solicitados.

POST: Crea un nuevo recurso, una buena práctica es devolver un enlace al recurso creado.

PUT: Actualiza un recurso ya creado, una buena práctica es devolver un enlace al recurso actualizado.

PATCH: Actualiza parcialmente un recurso existente, una buena práctica es devolver un enlace al recurso creado.

DELETE: Elimina un recurso, una buena práctica es devolver un estado HTTP 204 (Not content) para confirmar que el recurso ha sido eliminado correctamente.

Nota: Un recurso o resource es la información u objeto que se expone mediante un URL que has creado. Puede ser una objeto como un User, un Role, etc.. hasta archivos PDF, imágenes entre otros. 

Para más detalles de los métodos POST, PUT y PATCH, puedes revisar más adelante la sección sobre HATEOAS.

 

En los siguientes párrafos explicaremos en detalle el estado HTTP más común y cuándo usarlos.

Permite que los métodos HTTP sean sobrescritos

Algunos clientes HTTP sólo pueden trabajar con las solicitudes GET y POST, por lo que es necesario permitir que el método se sobrescriba (X-HTTP-Method-Overrid) permitiendo la sustitución de un POST a una solicitud PUT, PATCH o DELETE. Esto sólo se utiliza para cambiar el comportamiento del método POST; GET nunca debe modificar ningún recurso del servidor

Uso correcto de los métodos HTTP

Si tus servicios web están devolviendo un estado HTTP 200 para cada tipo de solicitud (correcta o incorrecta) e igualmente enviando el estado HTTP 500 en cada error, enfrentarás diferentes problemas tratando de identificar la pieza que está fallando en tu servidor debido a la escasa información que brinda ese estado de HTTP. A continuación puedes encontrar los usos de cada rango de estado HTTP:

1xx (100 – 199): Estado informativo.

2xx (200-299): Estado exitoso, algunas respuestas de este rango son: 200 (OK) que significa solicitud satisfactoria o 201 (No contenido), lo que significa que un recurso ha sido eliminado correctamente.

3xx (300-399): Redirección, esta respuesta indica que falta un paso para poder finalizar la solicitud, de modo que se intentará redireccionarla para obtenerla.

4xx (400-499): Error del lado del cliente. Es común devolver siempre un estado HTTP 400 para diferentes tipos de errores. La forma correcta de utilizar éste es identificar si el error se debió a algo del lado del cliente o del servidor. Por ejemplo, una respuesta HTTP 404 se produce cuando un cliente está intentando recuperar un recurso inexistente. Un estado HTTP 403 se produce cuando un cliente no tiene acceso para recuperar un recurso específico.

5xx (500-599): Error del lado del servidor. De forma similar al estado anterior, el desarrollador debe tener en cuenta el origen de un error para identificar si éste procede del cliente o del servidor. Este tipo de errores están relacionados con algo malo en el servidor, por ejemplo una mala conexión con la base de datos.

Nota: Para más detalle de los códigos de estado HTTP visitar este link

Si para cada solicitud tus servicios web REST están devolviendo un estado correcto, el cliente será capaz de entender y manejar cualquier error de la mejor manera. Aquí tienes un ejemplo de un endpoint con cada una de sus posibles respuestas.

Método: GET    Endpoint: /users/123

Descripción: Devuelve un usuario con el ID especificado.

Respuestas:

  • HTTP 200: El usuario existe y el cliente tiene acceso a este recurso. Devolverá un archivo JSON con los datos solicitados.
  • HTTP 404: El usuario solicitado no existe. Esto devolverá un archivo JSON con un mensaje de error.
  • HTTP 403: El cliente ha sido autenticado pero no está autorizado para obtener el recurso especificado. Se devolverá un archivo JDSON con el mensaje de error.

Utiliza HATEOAS (Hypermedia as Engine of Application State)

Utilizar HATEOAS proporciona una gran experiencia de usuario cuando se trabaja con una API que te permite entender cada servicio web sin utilizar ningún tipo de documentación. Puedes revisar un ejemplo de esta herramienta en la siguiente publicación: Spring Boot + REST Jersey (Uso de Spring HATEOAS y DTO) parte 3.

Utilice sólo SSL para todas sus peticiones

Muchos usuarios suelen conectar su aplicación usando redes públicas que pueden ser fácilmente intervenidas por cualquier persona, debido a estos casos es necesario que todas las solicitudes sean procesadas a través de una conexión SSL.

Documentación de la API

La documentación de una API REST no es tan compleja y tediosa como lo era hace unos años, ahora puedes encontrar diferentes herramientas para generar peticiones de emulación de documentación y generar snippets de código para que los clientes que utilizan diferentes lenguajes de programación. Una buena recomendación de este tipo de herramientas es https://apiary.io/.

Paginación

Hay endpoints que pueden devolver una gran cantidad de registros que a veces es difícil de manejar debido a los recursos disponibles en el lado del cliente (aplicaciones móviles). El siguiente snippet de código ilustra cómo utilizar la paginación dentro de una solicitud GET:

GET /tweets?offset=20&limit=10

Versionando tu API

Nunca ejecutes una API sin una versionar, ya que habrá momentos en los que será necesario modificar el comportamiento de algunos servicios web, para esto, es mejor tener diferentes versiones para que puedas asegurarte de que estás usando la versión más reciente del código. Puedes agregar esto a un endpoint así:

/application/api/v1

Autenticación

Como lo mencionamos anteriormente, una API de REST debe ser stateless, esto significa que cada solicitud debe enviarse a un mecanismo de autenticación como OAuth 2. Este tipo de solicitudes deben gestionarse mediante una conexión SSL.

Utiliza siempre un framework ligero

Hoy en día los servicios web de REST son ampliamente utilizados en diferentes arquitecturas de micro servicios destinados a ejecutar tareas simples. Es por eso que es mejor trabajar con ambientes ligeros proporcionando una forma sencilla de crear y codificar aplicaciones. Algunas herramientas recomendadas para trabajar con REST son SpringBoot y Dropwizard.

Las prácticas presentadas en este post son independientes del lenguaje ya que cualquier API REST puede seguirlas.

 

Fuente: https://geeks-mexico.com./2017/06/09/best-practices-for-better-restful-web-services/

Enviar comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *