Guía de buenas prácticas para crear una API Rest

Las API Rest las vemos en todas partes: desde aplicaciones web de todo tipo como blogs y redes sociales, hasta servicios más específicos como apps bancarias o videojuegos multiugador. Por lo tanto, podemos decir que son el pan de día de millones de desarrolladores.

Pero a grandes rasgos ¿Qué es una API Rest?

En palabras simples, es una de las muchas formas de crear APIs para conectar servicios con clientes dentro de una red. Pero en el caso específico de REST, utiliza como base el protocolo HTTP, de ahí su uso tan extendido en aplicaciones web.

Pese a la gran popularidad de REST hoy en día, lo cierto es que no hay un estándar de como se debe hacer una API de este tipo. Sin embargo, hay una serie de recomendaciones que pueden ayudar a que las API funcionen de mejor manera.

Es por eso que el día de hoy te traigo una lista de buenas prácticas que debes tener en cuenta la próxima vez que crees tu API Rest.

Usar correctamente los verbos HTTP

Es importante utilizar los verbos HTTP estándar (GET, POST, PUT, DELETE, PATCH, etc.) de acuerdo con sus significados convencionales, ya que esto facilita la comprensión de la API por parte de los desarrolladores y asegura una interoperabilidad consistente.

A grandes rasgos, los métodos tienen una funcionalidad similar a los de los CRUD, es decir, crean, acceden, modifican y eliminan recursos dentro del servidor.

De acuerdo a las convenciones, estas son las tareas que realiza cada método:

  • GET: se usa para acceder a recursos al servidor sin modificarlos.
  • POST: crea uno o varios recursos en el servidor.
  • PUT: es usado para actualizar un recurso existente.
  • DETLETE: se utiliza para eliminar elementos.

Crear versiones

El crear distintas versiones te permite agregar funcionalidades sin afectar los servicios que ya están desarrollados.

Imagina que vas a agregar un nuevo esquema de bases de datos, pero tu API ya la usan decenas de desarrolladores. ¿Harías el cambio a pesar de que terminarás rompiendo las aplicaciones de tus clientes? Lo más seguro es que no, por eso es importante tener versiones y definirlas en los endpoints de tus API.

Ejemplo

api/v1/students
api/v2/students
api/v3/students

Usar los códigos HTTP en las respuestas

Los códigos HTTP son una gran ayuda tanto para el frontend como el del backend, ya que te permiten conocer el estado exacto de las consultas.

Estos son algunos de los códigos Web que puede utilizar.

  1. Respuestas informativas:
    • 100: Continuar
    • 101: Cambio de protocolo
    • 102: Procesando
  2. Respuestas exitosas:
    • 200: OK
    • 201: Creado
    • 202: Aceptado
    • 204: Sin contenido
  3. Redirecciones:
    • 300: Múltiples opciones
    • 301: Movido permanentemente
    • 302: Encontrado
    • 304: No modificado
    • 307: Redirección temporal
    • 308: Redirección permanente
  4. Errores del cliente: – 400: Solicitud incorrecta – 401: No autorizado – 403: Prohibido – 404: No encontrado – 405: Método no permitido – 406: No aceptable – 408: Tiempo de espera de solicitud – 410: Ya no disponible – 429: Demasiadas solicitudes
  5. Errores del servidor:
    • 500: Error interno del servidor
    • 501: No se ha implementado
    • 502: Puerto de enlace incorrecto
    • 503: Servicio no disponible
    • 504: Gateway Timeout. No pudo obtener una respuesta a tiempo
    • 505: Versión HTTP no compatible
    • 511: Autenticación de red requerida

Así que la próxima vez trata de evitar poner en tus respuestas solo estatus 200 o 500.

Definir las rutas con sustantivos (en plural) y evitar usar verbos

Las APIs Rest son usadas para guardar y usar recursos, por esa razón los endpoints siempre se deben definir como sustantivos.

Ejemplo de como definir las rutas ✅:

api/v1/workouts

api/v4/users

Y hay que evitar cosas como ❌:

/getUser

/selectWorkouts

Por cierto, como regla general los sustantivos siempre se escriben en el plural.

Agregar funcionalidades como filtros, paginación y ordenamiento en atributos

Como mencioné en el punto anterior, las API Rest se usan para guardar recursos, por lo que los endpoints son siempre sustantivos.

Sin embargo eso no significa qur no se le puedan agregar funcionalidades, incluso lo ideal es siempre agregar algunas tareas comunes como pueden ser filtros de búsqueda, cantidad máxima de elementos, funciones de ordenamiento, paginación, etc., ya que te ayudarán a ahorrar recursos.

Para agregar estas funcionalidades, debes usar los atributos adicionales.

Ejemplo:

/api/v2/tasks?page=1
/api/v4/recipes?length=10&ingredinets=lemon

Usar caché (solo cuando sea necesario)

El almacenamiento en cache permite optimizar y ahorrar recursos valiosos, por lo que es una opción que hay que tener en cuenta si tu API empieza a tener cada vez más peticiones.

Entre las tecnologías que hay en el mercado más conocidas y usadas para el desarrollo de APIs están Redis y Memcached.

Aunque en algunos caos el usar el almacenamiento en caché puede llegar a optimizar el tiempo de respuesta hasta un 90%, eso no significa que sea la panacea, incluso puede llegar a ser contraproducente. Por eso tienes que considerar los siguiente:

  • Los datos que se almacenan pueden quedar obsoletos en el caso de que haya muchas actualizaciones
  • Hay una pequeña latencia, así que pueden existir inconsistencias.

Entonces, ¿Cuándo usarse el caché? Lo ideal es que te preguntes: «¿Estos datos fácilmente se pueden almacenar en un archivo estático?». Si la respuesta es «Sí», puedes usar el almacenamiento en caché sin problemas.

Crea documentación

Aunque este punto sea lógico para algunos, es cierto que hay muchos desarrolladores que no documentan sus APIs.

Tal vez si trabajas solo no hay tanto problema si no documentar tus API, pero lo ideal es siempre tener al menos definidos los endpoints, los tipos de de parámetros que se recibirán y las respuestas que dará.

Por fortuna, hay herramientas muy útiles que te permiten documentar agregando algunos cuantos comentarios en el código, como lo son Swagger, Apigee o el mismo Postman .También hay otras opciones propias de los lenguajes como JavaDoc o XML documentarion.

Al final lo importante es definir bien las rutas y los recursos que estas manejan.

Uso de CORS

El CORS es un mecanismo que se utiliza para restringir el acceso a recursos de un servidor a través de navegadores.

Aunque muchas veces los desarrolladores tratamos de habilitar que cualquier dominio pueda realizar consultas a nuestra API, lo recomendable es definir políticas como el Access-Control-Allow-Origin por temas seguridad y rendimiento.

Por ejemplo, en Express se puede definir el Access-Control-Allow-Origin de la siguiente manera.

app.get('/books', (req, res)=> {
	//Se define en el header de la respiesta elControl-Allow-Origin
	res.header('**Access-Control-Allow-Origin**', '<http://midominio.com>')
	//	...  
});

Resumen

Para recapitular esta guía, estas son las prácticas que se deben tener en cuenta:

  1. Usar de forma correcta verbos HTTP
  2. Crear versiones de código
  3. Nombrar recursos de forma plural
  4. Agregar funcionalidades como filtros y paginación a través de atributos opcionales.
  5. Crear documentación de las API.
  6. Usar el almacenamiento en la memoria caché para mejorar el rendimiento de tus API.
  7. Usar las cabeceras CORS.

Conclusión

Crear una API Rest de manera adecuada y siguiendo buenas prácticas trae muchos beneficios a largo plazo, ya que aumenta el grado de mantenibilidad y legibilidad en los proyectos.

Para el caso de Rest, es fundamental usar de manera adecuadas recursos dados en el protocolo HTTP, como por ejemplo los verbos HTTP (GET, POST, PUT, DELETE), las códigos de respuesta y las cabeceras CORS.

Aunque la implementación del API dependerá mucho de la tecnología, lenguaje o framework que se utilizará, al final la estructura suele ser la misma. Por lo tanto, estas prácticas son totalmente agnósticas al código.

TaggedAPI REST