Buenas prácticas para desarrollo API RESTful – Parte 2

En un artículo anterior hablamos de la importancia de seguir las buenas prácticas de desarrollo de una API RESTful.

Métodos HTTP (verbos)

HTTP ha definido algunos conjuntos de métodos que indican el tipo de acción que se realizará en los recursos.

Ahora es importante entender que son los métodos HTTP, para esto vamos a decir que la URL es una oración, donde los recursos son sustantivos y los métodos HTTP son los verbos.

Los métodos HTTP importantes son los siguientes:

• El método GET solicita datos del recurso y no debe producir ningún efecto secundario.
  Ej. /companies/3/employees devuelve la lista de todos los empleados de la compañía 3.
• El método POST solicita al servidor que cree un recurso en la base de datos, principalmente cuando se envía un formulario web.
  Ej. /companies/3/employees crea un nuevo empleado de la compañía 3.
  POST no es idempotente, lo que significa que múltiples solicitudes tendrán diferentes efectos.
• El método PUT solicita al servidor que actualice el recurso o cree el recurso, si no existe.
  Ej. /companies/3/employees/john solicitará que el servidor actualice, o cree, si no existe, el recurso john en la colección de empleados de la compañía 3.
  PUT es idempotente, lo que significa que múltiples solicitudes tendrán los mismos efectos.
• El método DELETE solicita que los recursos, o su instancia, se eliminen de la base de datos.
  Ej. /companies/3/employees/john/ solicitará al servidor que elimine el recurso john de la colección de empleados de la empresa 3.

Sin embargo existe otros métodos HTTP adicionales que también tienen su uso, pero en este artículo solo vamos a hacer mención a esto 4 métodos HTTP, ya que son los más usados dentro del desarrollo de una API Restful.

Códigos de estado de respuesta HTTP

Cuando el cliente envía una solicitud al servidor a través de una API, el cliente debe conocer los comentarios, si falló, se aprobó o si la solicitud fue incorrecta. Los códigos de estado HTTP son un grupo de códigos estandarizados que tienen varias explicaciones en varios escenarios. El servidor siempre debe devolver el código de estado correcto.
Las siguientes son las categorías importantes de los códigos HTTP:

2xx (categoría de éxito)

Estos códigos de estado representan que la acción solicitada fue recibida y procesada con éxito por el servidor.

• 200 Ok. La respuesta HTTP estándar representa el éxito para GET, PUT o POST.
• 201 Creado. Este código de estado debe devolverse cada vez que se crea la nueva instancia. Por ejemplo, al crear una nueva instancia, utilizando el método POST, siempre se debe devolver el código de estado 201.
• 204 Ningún contenido representa que la solicitud se procesó correctamente, pero no ha devuelto ningún contenido.

La API DELETE /companies/43/employees/2 eliminará el empleado 2 y, a cambio, no necesitamos ningún dato en el cuerpo de respuesta de la API, ya que solicitamos explícitamente al sistema que eliminara. Si hay algún error, como si el empleado 2 no existiera en la base de datos, entonces el código de respuesta no sería de la categoría de éxito 2xx sino de la categoría de error de cliente 4xx.

3xx (Categoría de redireccionamiento)

• 304 No modificado, indica que el cliente ya tiene la respuesta en su caché. Y por lo tanto, no hay necesidad de transferir los mismos datos de nuevo.

4xx (Categoría de error del cliente)

Estos códigos de estado representan que el cliente ha presentado una solicitud defectuosa.

• 400 Solicitud incorrecta, indica que la solicitud del cliente no se procesó, ya que el servidor no pudo entender lo que solicita el cliente.
• 401 No autorizado, indica que el cliente no tiene permiso para acceder a los recursos y debe volver a solicitar con las credenciales necesarias.
• 403 Prohibido, indica que la solicitud es válida y que el cliente está autenticado, pero al cliente no se le permite acceder a la página o al recurso por ningún motivo. Por ejemplo, a veces el cliente autorizado no puede acceder al directorio en el servidor.
• 404 No encontrado, indica que el recurso solicitado no está disponible ahora.
• 410 Gone, indica que el recurso solicitado ya no está disponible y que se ha movido intencionalmente.

5xx (Categoría de error del servidor)

• 500 Error interno del servidor, indica que la solicitud es válida, pero el servidor está totalmente confundido y se le pide al servidor que cumpla alguna condición inesperada.
• 503 Servicio no disponible, indica que el servidor está inactivo o no está disponible para recibir y procesar la solicitud. Sobre todo si el servidor está en mantenimiento.

De la misma manera que los métodos HTTP, también existen muchos más estados de respuesta, pero como se trata de una guía de mejores prácticas las acá descritas son las que más se usa.

Búsqueda, clasificación, filtrado y paginación

Todas estas acciones son simplemente la consulta en un conjunto de datos. No habrá un nuevo conjunto de API para manejar estas acciones. Necesitamos adjuntar los parámetros de consulta con el método GET API.
Entendamos con algunos ejemplos cómo implementar estas acciones.

• Clasificación En caso de que el cliente desee obtener la lista ordenada de empresas, el punto final GET /companies debería aceptar múltiples parámetros de clasificación en la consulta.
  GET /companies?sort=rank_asc clasificaría las compañías por su rango en orden ascendente.
• Filtrado Para filtrar el conjunto de datos, podemos pasar varias opciones a través de los parámetros de consulta.
  GET /companies?category=banking&location=bolivia filtraría los datos de la lista de compañías con la categoría de empresa de Banca y donde la ubicación es Bolivia.
• Búsqueda Al buscar el nombre de la compañía en la lista de compañías, el punto final de la API debería ser GET /companies?search=rootnite
• Paginación Cuando el conjunto de datos es demasiado grande, dividimos el conjunto de datos en partes más pequeñas, lo que ayuda a mejorar el rendimiento y es más fácil manejar la respuesta.
  Ej.  GET  /companies?page=23significa obtener la lista de empresas en la página 23.

Si agregar muchos parámetros de consulta en los métodos GET hace que el URI sea demasiado largo, el servidor puede responder con 414 URI. Estado HTTP demasiado largo, en esos casos, los parámetros también se pueden pasar en el cuerpo de la solicitud del método POST.

Versiones

Cuando el mundo está consumiendo sus API, la actualización de las API con algún cambio importante también llevaría a romper los productos o servicios existentes utilizando sus API.

https://api.yourservice.com/v1/companies/34/employees

La URL anterior un buen ejemplo, que tiene el número de versión de la API en la ruta. Si hay alguna actualización importante, podemos nombrar el nuevo conjunto de API como v2 o v1.x.x

Conclusión

Estas pautas están compiladas  en base a mi experiencia de desarrollo. Me encantaría conocer sus puntos de vista sobre los puntos mencionados anteriormente. ¡Por favor, deja un comentario y hazme saber!