Por qué necesitas un portal para desarrolladores de API para facilitar el descubrimiento de API

NGINX | 06 de diciembre de 2022

Las empresas dependen cada vez más de las API para conectar aplicaciones y datos entre distintas áreas de negocio, integrarse con socios y ofrecer experiencias a sus clientes. Según TechRadar, actualmente una empresa utiliza de media un total de 15.564 API, lo que supone un aumento interanual del 201 %.

A medida que el número de API sigue creciendo, aumenta la complejidad de gestionar su cartera de API. Cada vez resulta más difícil descubrir y hacer un seguimiento de las API disponibles y de dónde se encuentran, así como encontrar documentación sobre cómo utilizarlas. Sin una estrategia integral de API, estas pueden proliferar más rápido de lo que sus equipos de operaciones de plataforma pueden gestionarlas. A este problema lo llamamos proliferación de API y en una publicación anterior explicamos por qué supone una amenaza tan importante. En esta publicación analizamos en detalle cómo puede combatir la proliferación de API mediante la creación de un portal para desarrolladores de API con la ayuda de NGINX.

Crea un inventario de tus API

En última instancia, las API no pueden ser útiles hasta que se utilizan, lo que significa que los consumidores de API necesitan una forma de encontrarlas. Sin los sistemas adecuados, la proliferación de API dificulta que los desarrolladores encuentren las que necesitan para sus aplicaciones. En el mejor de los casos, las distintas áreas de negocio mantienen listas de API y el conocimiento se comparte entre equipos a través de redes informales de ingenieros.

Uno de los primeros pasos para combatir la proliferación de API es crear una única fuente de información fiable para sus API. Este proceso comienza con la elaboración de un inventario de sus API. Sin embargo, mantener un inventario preciso supone todo un reto, ya que cambia constantemente a medida que se introducen nuevas API y se retiran las antiguas. También debe localizar cualquier «API en la sombra» presente en sus entornos: API que han caído en el olvido con el tiempo, que se retiraron de forma incorrecta o que se crearon al margen de sus procesos estándar.

Las API no gestionadas son uno de los síntomas más perniciosos de la proliferación de API, ya que conllevan tanto implicaciones evidentes para la seguridad como costes ocultos. Sin un inventario preciso de las API disponibles, los equipos responsables deben dedicar tiempo a buscar documentación. Existe un riesgo considerable de duplicar esfuerzos innecesariamente cuando distintos equipos desarrollan funcionalidades similares. Además, los cambios en una API determinada pueden provocar costosas cadenas de trabajo adicional o incluso interrupciones del servicio si no se cuenta con un control de versiones adecuado.

Técnicas como la detección automatizada de API pueden ayudarle a identificar y tratar el síntoma de las API no gestionadas. Sin embargo, para resolver el problema, debe eliminar las causas fundamentales: procesos deficientes y falta de responsabilidad. En la práctica, integrar el inventario y la documentación de las API en sus canalizaciones de CI/CD es el único enfoque que garantiza la visibilidad de toda su cartera de API a largo plazo. En lugar de tener que realizar un seguimiento manual de cada API a medida que se pone en funcionamiento, solo tendrá que identificar y corregir las excepciones.

Optimiza el descubrimiento de API con un portal para desarrolladores de API

Un portal para desarrolladores de API puede ayudar, entre otras cosas, a agilizar el descubrimiento de API. Proporciona un lugar centralizado donde los consumidores de API pueden descubrirlas, consultar la documentación y probarlas antes de integrarlas en sus aplicaciones. El portal para desarrolladores de API también puede servir como catálogo central de API e incluir información sobre sus responsables y datos de contacto, para que todos sepan quién se encarga del mantenimiento de las API de los distintos servicios.

Un componente fundamental de nuestra arquitectura de referencia de API<.htmla>, un portal para desarrolladores de API eficaz permite abordar varios casos de uso clave:

Como parte de su estrategia de API, debe determinar cómo mantener su portal para desarrolladores de API. Necesita un enfoque automatizado que requiera poca intervención y que integre a la perfección la publicación, el control de versiones y la documentación de las API sin generar más trabajo para sus equipos de API.

Cree una única fuente de información fiable para sus API con NGINX

Para facilitar la detección de las API, debe crear una única fuente de información fiable donde los desarrolladores puedan encontrar sus API, aprender a utilizarlas e incorporarlas a sus proyectos. Para ello, necesitará un portal para desarrolladores y documentación actualizada.

API Connectivity Manager, que forma parte de F5 NGINX Management Suite, le ayuda a integrar la publicación, el control de versiones y la documentación de las API directamente en sus flujos de trabajo de desarrollo, para que su portal para desarrolladores de API esté siempre actualizado. Además de facilitar la creación de portales para desarrolladores en los que alojar sus API y su documentación, API Connectivity Manager le permite añadir páginas personalizadas y adaptar por completo el portal para desarrolladores a su identidad de marca.

Veamos cómo API Connectivity Manager le ayuda a abordar algunos casos de uso específicos. Consulte la documentación de API Connectivity Manager para obtener instrucciones detalladas sobre cómo configurar un clúster de portales para desarrolladores y publicar un portal para desarrolladores.

Generar automáticamente la documentación de la API

A menudo existe una gran brecha entre el nivel de calidad y detalle que los consumidores de su API esperan de la documentación y lo que sus desarrolladores de API, con una gran carga de trabajo, pueden ofrecer de forma realista con tiempo y recursos limitados. Muchas herramientas de documentación desarrolladas internamente no se integran con el ciclo de vida del desarrollo ni con otros sistemas de ingeniería. Pero no tiene por qué ser así.

Cómo puede ayudar NGINX: API Connectivity Manager utiliza la especificación OpenAPI para publicar API en la puerta de enlace de API y generar automáticamente la documentación correspondiente en el portal para desarrolladores, lo que ahorra tiempo a los desarrolladores de API y garantiza que los consumidores de API siempre puedan encontrar lo que necesitan. Puede cargar archivos de la especificación OpenAPI directamente a través de la interfaz de usuario de API Connectivity Manager o enviando una llamada mediante la API REST. Esto facilita la automatización del proceso de documentación a través de su canalización de CI/CD.

Para publicar documentación en API Connectivity Manager, haga clic en «Servicios» en la columna de navegación izquierda para abrir la pestaña «Servicios». Haga clic en el nombre de su espacio de trabajo o cree uno nuevo.

Una vez en el espacio de trabajo, haga clic en API Docs debajo del cuadro que contiene el nombre y la descripción de su espacio de trabajo (example-api en la captura de pantalla). A continuación, haga clic en el botón Add API Doc para cargar el archivo de especificación OpenAPI. Haga clic en el botón Save para publicar la documentación en el portal para desarrolladores.

Figura 1: Creación de documentación mediante la carga de un archivo de especificación OpenAPI en
API Connectivity Manager

Garantizar un control de versiones adecuado

Los cambios de versión deben gestionarse siempre con cuidado, especialmente en entornos de microservicios, donde muchos servicios pueden interactuar con una única API. Si no se adopta un enfoque cuidadoso para introducir nuevas versiones y retirar las antiguas, un solo cambio incompatible puede provocar una interrupción en cascada en decenas de microservicios.

Cómo puede ayudar NGINX: El uso de archivos de especificación OpenAPI con API Connectivity Manager permite controlar fácilmente las versiones de sus API. Además de establecer el número de versión, puede proporcionar documentación para cada versión y gestionar su estado (más reciente, activa, retirada u obsoleta).

Para publicar una nueva versión de una API, haga clic en «Servicios» en la columna de navegación izquierda. Haga clic en el nombre de su espacio de trabajo en la tabla y, a continuación, en el nombre de su entorno en la página que se abre. Después, haga clic en el botón «+ Añadir proxy». Desde aquí puede cargar la especificación OpenAPI, establecer la ruta base y la versión para crear el URI (por ejemplo, «/api/v2/») e introducir otros metadatos importantes. Haga clic en el botón «Publicar» para guardar y publicar el proxy de su API.

La versión original de la API sigue estando disponible junto con la nueva versión. De este modo, los usuarios disponen de tiempo para migrar gradualmente sus aplicaciones o servicios a la versión más reciente. Cuando esté listo, puede retirar por completo la versión original de la API. La figura 2 muestra dos versiones de la API Sentence Generator publicadas y en producción.

Figura 2: Gestión de las versiones activas de la API en API Connectivity Manager

Generar credenciales de API

Para impulsar la adopción de tus API, debes simplificar al máximo el proceso de incorporación de sus consumidores. Una vez que los usuarios encuentren las API, necesitarán un método para iniciar sesión de forma segura en el portal para desarrolladores y generar credenciales. Estas credenciales les permiten acceder a las funcionalidades de tu API. En la mayoría de los casos, conviene implementar un flujo de trabajo autogestionado para que los usuarios puedan registrarse por su cuenta.

Cómo puede ayudar NGINX: API Connectivity Manager admite flujos de trabajo de API autogestionados en el portal para desarrolladores, de modo que los usuarios puedan generar sus propias credenciales de recursos para acceder a las API. Las credenciales de recursos se pueden gestionar en el portal mediante claves de API o autenticación HTTP básica. También puede habilitar el inicio de sesión único (SSO) en el portal para desarrolladores a fin de proteger el acceso y permitir que los consumidores de API autenticados gestionen las credenciales de recursos.

Para habilitar rápidamente el SSO en el portal para desarrolladores, haga clic en Infraestructura en la columna de navegación de la izquierda. Haga clic en el nombre de su espacio de trabajo en la tabla (en la Figura 3, es team-sentence).

Figura 3: Lista de espacios de trabajo en la pestaña Infraestructura

En la tabla de la página del espacio de trabajo, haga clic en el nombre del entorno que desea configurar (en la figura 4, es prod).

Figura 4: Lista de entornos de un espacio de trabajo

En la sección Clústeres del portal para desarrolladores, haga clic en el icono … de la columna Acciones correspondiente al portal para desarrolladores en el que está trabajando y seleccione Editar configuración avanzada en el menú desplegable. En la figura 5, el único clúster del portal para desarrolladores es devportal-cluster.

Figura 5: Selección de la opción Edit Advanced Config para un clúster del portal para desarrolladores

A continuación, haga clic en Políticas globales en la columna de navegación izquierda. Para configurar la política de usuario de confianza de OpenID Connect, haga clic en el icono … de la columna Acciones de su fila y seleccione Editar política en el menú desplegable. Para obtener más información, consulte la documentación de API Connectivity Manager.

Figura 6: Configuración de la política global de la parte de confianza de OpenID Connect para habilitar el inicio de sesión único

Pruebe las API en el portal para desarrolladores

Una forma de medir el éxito de su estrategia de API es realizar un seguimiento de la métrica «tiempo hasta la primera llamada a la API», que indica cuánto tarda un desarrollador en enviar una solicitud básica con su API.

Hemos establecido que una documentación clara y concisa es esencial como primer punto de acceso a tu API, ya que permite a los usuarios adquirir una comprensión básica de cómo trabajar con ella. Por lo general, los desarrolladores deben escribir código nuevo para integrar la API en su aplicación antes de poder probar las solicitudes a la API. Puedes ayudarles a empezar mucho más rápido ofreciéndoles una forma de interactuar directamente con una API desde el portal para desarrolladores utilizando datos reales; de este modo, podrán realizar su primera llamada a la API sin escribir una sola línea de código para su aplicación.

Cómo puede ayudar NGINX: Una vez que habilite el inicio de sesión único (SSO) en los portales para desarrolladores de API Connectivity Manager, los consumidores de la API podrán utilizar API Explorer para probar llamadas a la API en las páginas de documentación. Podrán usar API Explorer para explorar los endpoints, los parámetros, las respuestas y los modelos de datos de la API, así como probar llamadas a la API directamente desde sus navegadores.

La figura 7 muestra el Explorador de API en acción; en este caso, probando la API del Generador de frases. El usuario selecciona las credenciales adecuadas, crea la solicitud y recibe una respuesta con datos reales de la API.

Figura 7: Prueba de una API en el portal para desarrolladores

Resumen

Las API son fundamentales para su organización. El primer paso para gobernarlas y protegerlas consiste en elaborar un inventario de todas ellas, estén donde estén. Sin embargo, descubrir las API es solo una parte de la solución: debe integrar el inventario, la documentación y el control de versiones de las API en el ciclo de vida de desarrollo e ingeniería para abordar las causas fundamentales de su proliferación.

Inicie una prueba gratuita de 30 días de NGINX Management Suite, que incluye acceso a API Connectivity Manager, NGINX Plus como puerta de enlace de API y a NGINX App Protect para proteger sus API.