¿Por qué necesitas un portal para desarrolladores de API para descubrir nuevas API?

Las empresas dependen cada vez más de las API para conectar aplicações y datos entre líneas de negocios, integrarse con socios y brindar experiencias a los clientes. Según TechRadar , hoy en día la empresa promedio utiliza un total de 15.564 API, un aumento del 201 % año tras año .

A medida que el número de API continúa creciendo , aumenta la complejidad de administrar su cartera de API. Cada vez es más difícil descubrir y rastrear qué API están disponibles y dónde se encuentran, así como encontrar documentación sobre cómo usarlas. Sin una estrategia de API holística, las API pueden proliferar más rápido de lo que los 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é es una amenaza tan importante. En esta publicación exploramos en detalle cómo puedes combatir la proliferación de API configurando un portal para desarrolladores de API con la ayuda de NGINX.

Cree un inventario de sus API

En última instancia, las API no pueden ser útiles hasta que se utilicen, 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 API que necesitan para sus aplicações. En el mejor de los casos, las listas de API las mantienen diferentes líneas de negocio y el conocimiento se comparte entre equipos mediante redes informales de ingenieros.

Uno de los primeros pasos para combatir la proliferación de API es crear una única fuente de verdad para sus API. Ese proceso comienza con la creación de un inventario de sus API. Sin embargo, llevar un inventario preciso es un desafío: es un objetivo en constante movimiento a medida que se introducen nuevas API y las antiguas quedan obsoletas. También debe encontrar "API ocultas" en sus entornos: API que se han olvidado con el tiempo, se dejaron obsoletas de forma incorrecta o se crearon fuera de sus procesos estándar.

Las API no administradas son uno de los síntomas más insidiosos de la proliferación de API, con obvias implicaciones de seguridad y costos ocultos. Sin un inventario preciso de las API disponibles, sus equipos de API deben dedicar tiempo a buscar documentación. Existe un riesgo significativo de que se produzcan esfuerzos duplicados e innecesarios a medida que varios equipos desarrollan una funcionalidad similar. Y los cambios en una API determinada pueden dar lugar a costosas cascadas de reelaboraciones o incluso interrupciones del servicio si no hay un control de versiones adecuado.

Técnicas como el descubrimiento automatizado de API pueden ayudarle a identificar y tratar el síntoma de las API no administradas. Pero para resolver el problema es necesario eliminar las causas fundamentales: procesos defectuosos y falta de propiedad. En la práctica, integrar el inventario y la documentación de API en sus pipelines de CI/CD es el único enfoque que garantiza la visibilidad de su cartera de API a largo plazo. En lugar de tener que rastrear manualmente cada API a medida que se conecta, solo necesita identificar y remediar las excepciones.

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

Agilizar el descubrimiento de API es un área en la que un portal para desarrolladores de API puede ayudar. Proporciona una ubicación central para que los consumidores de API descubran API, lean documentación y prueben API antes de integrarlas en sus aplicações. Su portal para desarrolladores de API también puede servir como catálogo central de API, completo con información de propiedad y contacto, para que todos sepan quién es responsable de mantener las API para los diferentes servicios.

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

• Optimice el descubrimiento de API : publique sus API en una ubicación accesible para que los desarrolladores puedan encontrarlas y usarlas fácilmente en sus proyectos.
• Proporcionar documentación clara y actualizada : asegúrese de que los desarrolladores siempre tengan acceso a la documentación más actualizada sobre cómo funciona una API.
• Garantizar el control de versiones adecuado : introducir nuevas versiones de una API sin crear interrupciones para las aplicações posteriores, con soporte para el control de versiones
• Generar credenciales de API : agilice el proceso de onboarding para que los desarrolladores puedan iniciar sesión y generar credenciales para usar para el acceso a la API.
• Pruebe las API : permita que los desarrolladores prueben las API en el portal antes de integrarlas en sus proyectos.

Como parte de su estrategia de API, debe descubrir cómo mantener su portal para desarrolladores de API. Necesita un enfoque automatizado y de bajo contacto que integre sin problemas la publicación, el control de versiones y la documentación de las API sin crear más trabajo para sus equipos de API.

Cree una única fuente de verdad para sus API con NGINX

Para permitir un descubrimiento de API sin inconvenientes, debe crear una única fuente de verdad donde los desarrolladores puedan encontrar sus API, aprender a usarlas e incorporarlas a sus proyectos. Eso significa que necesitarás un portal para desarrolladores y documentación actualizada .

API Connectivity Manager , parte de F5 NGINX Management Suite, lo 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 nunca esté desactualizado. Además de facilitar la creación de portales para desarrolladores de API para alojar sus API y documentación, API Connectivity Manager le permite agregar páginas personalizadas y personalizar completamente el portal para desarrolladores para que coincida con su 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 portal para desarrolladores y publicar un portal para desarrolladores .

Generar automáticamente documentación de API

A menudo existe una gran brecha entre el nivel de calidad y detalle que los consumidores de API esperan de la documentación y lo que sus ocupados desarrolladores de API pueden ofrecer de manera realista con tiempo y recursos limitados. Muchas herramientas de documentación locales no logran integrarse con el ciclo de vida del desarrollo ni con otros sistemas de ingeniería. Esto 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 adjunta 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 especificación de OpenAPI directamente a través de la interfaz de usuario del Administrador de Conectividad de API o mediante una llamada a través de la API REST. Esto facilita la automatización del proceso de documentación mediante 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 que esté en el espacio de trabajo, haga clic en Documentos de API debajo del cuadro que tiene el nombre y la descripción de su espacio de trabajo ( ejemplo-api en la captura de pantalla). Simplemente haga clic en el botón Agregar documento API para cargar su archivo de especificación OpenAPI. Haga clic en el botón Guardar para publicar la documentación en el portal para desarrolladores.

Asegúrese de tener una versión adecuada

Los cambios de versión siempre deben gestionarse con cuidado, especialmente en entornos de microservicios donde muchos servicios pueden interactuar con una sola API. Sin un enfoque cuidadoso al introducir nuevas versiones y retirar las antiguas, un solo cambio disruptivo puede provocar una interrupción en cascada en docenas de microservicios.

Cómo puede ayudar NGINX: El uso de archivos de especificación OpenAPI con API Connectivity Manager permite un fácil control de versiones para sus API. Además de configurar el número de versión, puede proporcionar documentación para cada versión y administrar 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, haga clic en el nombre de su entorno en la página que se abre. A continuación, haga clic en el botón + Agregar proxy . Desde aquí puede cargar la especificación OpenAPI, establecer la ruta base y la versión para crear la URI (por ejemplo, /api/v2/ ) e ingresar otros metadatos importantes. Haga clic en el botón Publicar para guardar y publicar su proxy API.

La versión original de la API sigue estando disponible junto con la nueva versión. Esto les da a sus usuarios tiempo para migrar gradualmente sus aplicações o servicios a la versión más reciente. Cuando esté listo, puede descontinuar por completo la versión original de su API. La Figura 2 muestra dos versiones de la API del generador de oraciones publicadas y en producción.

Generar credenciales de API

Para impulsar la adopción de sus API, debe hacer que el proceso de onboarding sea lo más simple posible para los consumidores de sus API. Una vez que los usuarios encuentran sus API, necesitan un método para iniciar sesión de forma segura en el portal para desarrolladores y generar credenciales. Estas credenciales les otorgan acceso a la funcionalidad de tu API. Normalmente, querrás 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 administrar en el portal mediante claves API o autenticación básica HTTP . También puede habilitar el inicio de sesión único (SSO) en el portal para desarrolladores para proteger el acceso y permitir que los consumidores de API autenticados administren 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 izquierda. Haga clic en el nombre de su espacio de trabajo en la tabla (en la Figura 3, es team-sentence ).

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

En la sección Clústeres del Portal para desarrolladores , haga clic en el ícono … en la columna Acciones del 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 .

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

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 revela cuánto tiempo le toma a un desarrollador 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 su API, donde sus usuarios adquieren una comprensión básica de cómo trabajar con ella. Normalmente, los desarrolladores deben escribir código nuevo para integrar la API en su aplicação antes de poder probar las solicitudes de la API. Puede ayudar a los desarrolladores a comenzar mucho más rápido al brindarles una forma de interactuar directamente con una API en el portal para desarrolladores usando datos reales, lo que les permite realizar efectivamente su primera llamada a la API sin escribir una sola línea de código para su aplicação.

Cómo puede ayudar NGINX: Una vez que habilite SSO para sus portales para desarrolladores de API Connectivity Manager, los consumidores de API podrán usar el Explorador de API para probar llamadas de API en sus páginas de documentación. Pueden usar API Explorer para explorar los puntos finales, parámetros, respuestas y modelos de datos de la API y probar llamadas API directamente con sus navegadores.

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

resumen

Las API son cruciales para su organización. Y el primer paso para gobernar y proteger sus API comienza con realizar un inventario de cada API, donde sea que esté. Pero el descubrimiento de API es solo una parte de la solución: es necesario crear un inventario, documentación y control de versiones de API en el ciclo de vida de desarrollo e ingeniería para abordar las causas fundamentales de la proliferación de API.

Comience 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 NGINX App Protect para proteger sus API.