Pautas de diseño de API RESTful: las mejores prácticas

Facebook, Google, Github, Netflix y algunos otros gigantes tecnológicos han dado la oportunidad a los desarrolladores y productos de consumir sus datos a través de API y se han convertido en una plataforma para ellos. Incluso si no está escribiendo API para otros desarrolladores y productos, es siempre es muy saludable para su aplicación tener API bellamente diseñadas.

Hay un largo debate en Internet sobre las mejores formas de diseñar las API, y es uno de los más matizados. No hay lineamientos oficiales definidos para el mismo.

La API es una interfaz a través de la cual muchos desarrolladores interactúan con los datos. Una API bien diseñada siempre es muy fácil de usar y facilita mucho la vida del desarrollador. La API es la GUI para los desarrolladores, si es confusa o no detallada, entonces el desarrollador comenzará a buscar alternativas o dejará de usarla. La experiencia de los desarrolladores es la métrica más importante para medir la calidad de las API.

La API es como un artista actuando en el escenario, y sus usuarios son la audiencia

1) Terminologías

Los siguientes son los términos más importantes relacionados con las API REST

• El recurso es un objeto o representación de algo, que tiene algunos datos asociados y puede haber un conjunto de métodos para operar en él. Por ejemplo, los animales, las escuelas y los empleados son recursos y eliminar, agregar y actualizar son las operaciones que se realizarán en estos recursos.
• Las colecciones son un conjunto de recursos, por ejemplo, Empresas es la colección de recursos de la empresa .
• URL (Uniform Resource Locator) es una ruta a través de la cual se puede ubicar un recurso y se pueden realizar algunas acciones en él.

2) punto final de la API

Escribamos algunas API para empresas que tienen algunos empleados, para comprender más. /getAllEmployees es una API que responderá con la lista de empleados. Algunas API más alrededor de una empresa se verán de la siguiente manera:

• _/addNewEmployee_
• _/updateEmployee_
• _/deleteEmployee_
• _/deleteAllEmployees_
• _/promoteEmployee_
• _/promoteAllEmployees_

Y habrá toneladas de otros puntos finales de API como estos para diferentes operaciones. Todos ellos contendrán muchas acciones redundantes. Por lo tanto, sería complicado mantener todos estos puntos finales de API cuando aumenta el número de API.

**¿Qué está mal?**La URL solo debe contener recursos (sustantivos), no acciones ni verbos. La ruta de la API /addNewEmployee contiene la acción addNew junto con el nombre del recurso Employee .

**Entonces, ¿cuál es la forma correcta?** /companies endpoint es un buen ejemplo, que no contiene ninguna acción. Pero la pregunta es cómo le informamos al servidor sobre las acciones que se realizarán en los recursos de companies , a saber. ya sea para agregar, eliminar o actualizar?

Aquí es donde los métodos HTTP (GET, POST, DELETE, PUT), también llamados verbos, juegan un papel.

El recurso siempre debe estar en plural en el extremo de la API y si queremos acceder a una instancia del recurso, siempre podemos pasar la identificación en la URL.

• el método GET path /companies debe obtener la lista de todas las empresas
• el método GET ruta /companies/34 debe obtener los detalles de la empresa 34
• método DELETE ruta /companies/34 debe eliminar la empresa 34

En algunos otros casos de uso, si tenemos recursos bajo un recurso, por ejemplo, empleados de una empresa, algunos de los puntos finales de la API de muestra serían:

• GET /companies/3/employees debe obtener la lista de todos los empleados de la empresa 3
• GET /companies/3/employees/45 debe obtener los detalles del empleado 45, que pertenece a la empresa 3
• DELETE /companies/3/employees/45 debe eliminar al empleado 45, que pertenece a la empresa 3
• POST /companies debe crear una nueva empresa y devolver los detalles de la nueva empresa creada

¿No son las API ahora más precisas y consistentes? 😎

Conclusión: las rutas deben contener la forma plural de recursos y el método HTTP debe definir el tipo de acción que se realizará en el recurso.

3) 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.

La URL es una oración, donde los recursos son sustantivos y los métodos HTTP son verbos.

Los métodos HTTP importantes son los siguientes:

1. 
   

   El método GET solicita datos del recurso y no debería producir ningún efecto secundario. Por ejemplo /companies/3/employees devuelve la lista de todos los empleados de la empresa 3.

2. 
   

   
   

   El método POST solicita al servidor que cree un recurso en la base de datos, principalmente cuando se envía un formulario web. Por ejemplo /companies/3/employees crea un nuevo empleado de la empresa 3. POST no es idempotente , lo que significa que múltiples solicitudes tendrán diferentes efectos.

3. 
   

   
   

   El método PUT solicita al servidor que actualice el recurso o cree el recurso, si no existe. Por ejemplo /companies/3/employees/john solicitará al servidor que actualice o cree, si no existe, el recurso john en la colección de empleados bajo la compañía 3. PUT es idempotente , lo que significa que varias solicitudes tendrán los mismos efectos.

4. 
   

   El método DELETE solicita que los recursos, o su instancia, se eliminen de la base de datos. Por ejemplo, /companies/3/employees/john/ solicitará al servidor que elimine el recurso john de la colección de empleados en la empresa 3.

Hay algunos otros métodos que discutiremos en otra publicación.

4) 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ó, pasó o si la solicitud fue incorrecta. Los códigos de estado HTTP son un montón 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 categorizaciones importantes de los códigos HTTP:

2xx (categoría de éxito)

Estos códigos de estado representan que el servidor recibió y procesó correctamente la acción solicitada.

• 200 Ok La respuesta HTTP estándar que representa el éxito de 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 debe devolver el código de estado 201.

• 
  

  
  

  204 Sin contenido representa que la solicitud se procesó con éxito, pero no ha devuelto ningún contenido. ELIMINAR puede ser un buen ejemplo de esto. La API DELETE /companies/43/employees/2 eliminará el empleado 2 y, a cambio, no necesitamos ningún datos en el cuerpo de respuesta de la API, ya que le pedimos explícitamente al sistema que los elimine. Si hay algún error, como si employee 2 no existe en la base de datos, entonces el código de respuesta no sería de la 2xx Success Category sino de la 4xx Client Error category .

3xx (categoría de redirección)

• 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 nuevamente.

4xx (categoría de error del cliente)

Estos códigos de estado representan que el cliente ha realizado 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 solicitarlo con las credenciales requeridas.
• 403 Prohibido indica que la solicitud es válida y 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 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 que atienda alguna condición inesperada.
• 503 Servicio no disponible indica que el servidor está inactivo o no disponible para recibir y procesar la solicitud. Sobre todo si el servidor está en mantenimiento.

5) Convención de mayúsculas y minúsculas del nombre de campo

Puede seguir cualquier convención de mayúsculas y minúsculas, pero asegúrese de que sea coherente en toda la aplicación. Si el cuerpo de la solicitud o el tipo de respuesta es JSON , siga camelCase para mantener la coherencia.

6) 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 agregar los parámetros de consulta con la API del método GET. Comprendamos con algunos ejemplos cómo implementar estas acciones.

• 
  

  Clasificación En caso de que el cliente desee obtener la lista ordenada de empresas, el extremo GET /companies debe aceptar varios parámetros de clasificación en la consulta. Por ejemplo GET /companies?sort=rank_asc clasificaría las empresas 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. Por ejemplo GET /companies?category=banking&location=india filtraría los datos de la lista de empresas con la categoría de empresa de Banking y donde la ubicación es India.

• Búsqueda Al buscar el nombre de la empresa en la lista de empresas, el extremo de la API debe ser GET /companies?search=Digital Mckinsey
• Paginación Cuando el conjunto de datos es demasiado grande, lo dividimos en partes más pequeñas, lo que ayuda a mejorar el rendimiento y facilita el manejo de la respuesta. P.ej. GET /companies?page=23 significa 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 un estado HTTP 414 URI Too long ; en esos casos, los parámetros también se pueden pasar en el cuerpo de la solicitud del método POST .

7) Versión

Cuando sus API están siendo consumidas por el mundo, actualizar las API con algún cambio importante también conduciría a romper los productos o servicios existentes que usan sus API.

http://api.yourservice.com/v1/companies/34/employees es 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.xx

Estas pautas se compilan en 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!

Si este artículo te ayudó, entonces puedes invitarme a un café 😊