Diseño y arquitectura de APIs: 10 buenas prácticas para construir una API sólida y escalable

En el desarrollo de una aplicación, el diseño y la arquitectura de su API pueden ser la diferencia entre el éxito y el fracaso.

Si una API está mal diseñada, puede generar problemas importantes que afectan tanto a los desarrolladores como a sus usuarios.

Entre los problemas más comunes derivados de un mal diseño de una API se incluyen dificultades para entenderla y utilizarla, un rendimiento pobre, incompatibilidad con diferentes clientes, problemas de seguridad y dificultad para escalar.

En consecuencia, es fundamental considerar una serie de factores clave al diseñar y construir una API sólida y escalable.

En este artículo exploraremos cómo crear una API que sea fácil de usar y mantener, escalable y segura.

Analizaremos diferentes patrones de arquitectura de API, tecnologías y herramientas, y te proporcionaremos consejos prácticos para esquivar los errores más comunes y maximizar las oportunidades de que tu API sea un éxito.

Al lío, comencemos.

Características de una API bien diseñada

Comenzamos explicando que características debe tener una API bien diseñada, de modo que nos sirva de guía a través de todo el artículo mientras detallamos las técnicas, patrones y herramientas para lograr el objetivo.

• Fácil de entender.
• Debe ser tan intuitiva que sea posible utilizarla incluso sin la documentación.
• Código limpio, claro y conciso, de modo que sea fácil de leer y mantener.
• Funcionalidades atómicas, cada función debe tener una única responsabilidad.
• Diseño escalable.
• Mínimo acoplamiento posible entre recursos.

► Lee también: Implementando una API con GraphQL

Problemas a los que te enfrentarás

Cuando desarrollas un sistema debes prepararte para enfrentar desafíos importantes a lo largo de toda su existencia.

El software, como la vida, evoluciona, y te vas a ver obligado tomar decisiones de diseño vitales desde el inicio, a riesgo de que se vuelva obsoleto e imposible de adaptar a nuevos entornos.

Veamos algunos problemas que se te pueden presentar:

• Cambios de escala: Este es quizás el más común. Sería de necios pensar que no vas a necesitar ampliar sus funcionalidades constantemente, por lo que debemos estar preparados generando funcionalidades atómicas y reutilizables.
• Cambios de requisitos: Los procesos a los que las APIs implementan también evolucionan, y es común que cambien los requisitos que se pactaron inicialmente en algún momento del ciclo de vida.
• Cambios de tecnología: Los lenguajes de programación, frameworks, mecanismos de seguridad y cifrado, etc, evolucionan constantemente, y la API debe ser capaz de afrontar dichos cambios satisfactoriamente.
• Cambios de integración: Aunque debemos tratar de evitar el acoplamiento, tu API siempre tendrá dependencias con librerías de terceros y otras tecnologías sujetas a cambios, y deberás ser capaz de adaptarte.

Elementos de diseño aplicables

Para evitar estos problemas, que son solo la punta de iceberg, debes estudiar elementos de arquitectura de software, utilizar patrones de diseño donde sean aplicables y, sobre todo, utilizar mucho el sentido común.

Para empezar, te dejo algunos de los elementos que no debes pasar por alto si tu intención es implementar una API decente.

Una API debe ser lo más pequeña posible

Debes tener en cuenta que mientras más cargues una funcionalidad, más reduces las posibilidades de integrarla con otras.

Siempre podrás agregar nuevas funcionalidades a tu API, pero una vez que los usuarios y sistemas comiencen a consumir tu contenido, será muy difícil y hasta imposible eliminar características.

Una API debe hacer una cosa y hacerla bien

El modo de funcionamiento de REST se basa en la atomicidad, no importa la cantidad de peticiones que el navegador envíe a el servidor mientras cada una de estas haga solo una operación de la mejor manera posible.

Esta es la clave para maximizar las oportunidades de integración mediante la aplicación del principio Don’t Repeat Yourself.

No debes exponer detalles de tu implementación como respuesta de la API

Debes tener mucho cuidado con la salida de tus funcionalidades, porque una vez que se acopla un sistema de terceros te será imposible cambiarla sin afectar su funcionamiento.

Por tanto, nunca retornes como respuesta alguna estructura susceptible a grandes cambios en el futuro.

Utilizar los nombres coherentemente

La API debe entenderse por sí sola, debido a que se integrarán a ella otras aplicaciones de terceros, debes facilitar esa integración. A continuación, algunas buenas prácticas en cuanto a nombres.

• Utilizar sustantivos en lugar de verbos en los endpoints.
• Siempre usar los mismos verbos para las mismas acciones. Por ejemplo, evitar utilizar get y retrieve, o delete y remove, bajo el mismo significado.
• Utilizar nombres descriptivos para recursos y acciones.
• Usar un anidamiento de endpoints lógico.

Uso de estándares

Debes ser cuidadoso para no confundir a los desarrolladores que acoplen sus sistemas a tu API.

Por ejemplo, es necesario utilizar las fechas en formato ISO internaciones, utilizar los códigos de errores estándar de HTTP en las responses para indicarle a los desarrolladores exactamente cual fue el problema que ocurrió durante la ejecución, entre otros.

Parámetros amigables

Evitar largas listas de parámetros en tus funcionalidades y piensa en el orden más lógico de los mismos, sobre todo si tienen el mismo tipo.

Para tener una idea, una métrica interesante puede ser retarnos a utilizar 3 parámetros como máximo.

Versionado de la API

Ante cualquier cambio que pueda afectar a algún cliente, debes dejar que él decida si migrar o quedarse con su versión actual.

Para esto debes planificar un esquema de versionado, donde pudieras comenzar agregando /v1/ a la API y cuando se empiece a escalar que sea inevitable hacer cambios en funcionalidades en uso, agregar la versión /v2/ y mantener la anterior funcionando.

Utilizar un esquema de seguridad sólido

Debes forzar el uso de la comunicación mediante el uso de SSL/TLS y mantener un buen mecanismo de autenticación y autorización bajo el principio del mínimo privilegio.

En este punto puedes visitar nuestro artículo sobre seguridad en las API para profundizar en este tema.

Implementa pruebas funcionales

Debes llevar las pruebas a la par del desarrollo. Esta es la clave para lograr una API estable, porque al principio puede parecer algo trivial y ciertamente roba tiempo, pero en el futuro será la mejor de las inversiones.

Si mantienes las pruebas al día, nunca tendrás problemas por cambiar alguna parte de tu código, ya que al correr las pruebas te aseguras que no se afecta ninguna de las otras funcionalidades.

Mirar con luz larga

Debes pensar desde el inicio de la implementación como enfrentar los problemas que te presenté al principio del artículo, unido a otros que puedan afectar el futuro desempeño de tu API.

Por ejemplo, siempre debes permitir el uso de filtros, ordenamiento y paginación desde el primer momento, aunque el tamaño de tu base de datos sea pequeño en el inicio.

Una buena documentación hace la diferencia

Mantén siempre actualizada la documentación de tu API, con una descripción completa de las funcionalidades, parámetros y retornos.

Apóyate en herramientas automáticas para generar documentación por metadatos en el código.

De este modo damos por terminado el artículo, donde hemos explorado los principios fundamentales del diseño y la arquitectura de APIs, proporcionando consejos prácticos para crear una API sólida y escalable.

Espero que la información brindada sea de utilidad para ti, hasta la próxima.

Quizás te interese: De SOAP a GraphQL pasando por REST: las tecnologías que nos han permitido el desarrollo de APIs