Apidocs Apigee

Función del Developer Portal

Cuando trabajamos con APIs es importante disponer de la información necesaria para poder utilizarlas correctamente y de forma ágil. La mejor forma de cubrir esta necesidad es mediante API Docs, que son la documentación asociada a cada una de las definiciones APIs que tengamos. El estándar para realizar esta documentación es conocido como OpenAPI o Swagger, el cual nos permite representar el servicio web y la información asociada de una forma sencilla y ordenada.

En la actualidad es muy frecuente utilizar diversas APIs para un mismo desarrollo, por tanto es necesario consultar de forma frecuente y ágil diversos API Docs. Esto crea la necesidad de un componente que permita acceder y consultar el listado completo de definiciones de forma rápida y sencilla, llamado API Portal o Developer Portal. El API Portal es un componente, usualmente un portal web, encargado de recopilar y almacenar toda la información relacionada con las APIs publicadas en el API Gateway. Este portal es el encargado de mostrar y gestionar los API Docs.

Otro aspecto importante del Developer Portal es el de la publicitación de las APIs. El Developer Portal, aparte de tener los API Docs publicados, también debe cubrir una buena Developer Experience, ofreciendo los contenidos de forma atractiva, tanto en estilo como en servicios (foros, FAQs, chatbots...), fomentando que los desarrolladores de aplicaciones acaben contratando las APIs publicadas en él.

Creación del Developer Portal

La creación de este componente se puede realizar de varias maneras dependiendo del producto utilizado. En el caso de Apigee ofrece dos alternativas para poder realizarlo:

  • De forma automática integrada en su plataforma web
  • Mediante el uso de módulos que ofrece Apigee para utilizar en Drupal

Creación automática en Apigee

Te permite realizar el API Portal mediante clics desde la plataforma web de Apigee de forma rápida, y ya integrada con las APIs, evitando la necesidad de añadir integración continua.

Las ventajas principales de utilizar esta modalidad son:

  • Tiempo de puesta en producción menor.
  • Integración out of the box con el API Management.
  • No es necesaria una administración ni operación compleja de la plataforma.
  • No requiere ningún conocimiento específico para crearlo.

Por otro lado, las desventajas son:

  • No se puede incluir ninguna funcionalidad customizada.
  • La personalización de estilos está limitada.
  • Como estándar de documentación solo admite OpenAPI y GraphQL Schema.

Creación mediante Drupal y módulos de Apigee

Drupal es un CMS (content management software) que gracias a sus módulos permite crear contenido de una forma muy fácil y flexible. Para el caso del API Portal, Drupal es una gran alternativa ya que Apigee ofrece módulos para facilitar la creación agilizando y facilitando mucho el proceso. Si se realiza un portal de Drupal específico para la creación del API Portal se podrá personalizar e incluir funcionalidades más complejas.

Algunas de las ventajas de utilizar este modelo son:

  • Posibilidad de añadir atributos a las APIs para la categorización.
  • Diseño de la página web completamente personalizada.
  • Capacidad para utilizar diferentes estándares de documentación de APIs como SmartDocs, Swagger o Redoc.
  • Los filtros se pueden realizar de manera ad hoc para el caso de uso.

Las principales desventajas respecto al portal generado automáticamente son:

  • El tiempo hasta la puesta en producción es mayor por la necesidad de realizar desarrollos.
  • Mayor necesidad de administración y operación.
  • Necesidad de realizar la integración con las APIs.

Digital Lover

Integración de Drupal mediante el módulo API Catalog

Al ser un portal independiente de Apigee, al contrario que si se crease de forma automática en la plataforma web, es necesario realizar la integración entre las APIs de Gateway y el API Portal para la carga y administración de las API Docs.

Para ello utilizaremos API Catalog, que es uno de los módulos diseñados por Apigee para el desarrollo de los API Portal en Drupal. Este módulo nos ofrece una API REST con la que podremos subir, modificar o eliminar nuestra documentación (API Docs) en el portal.

Automatización de la gestión de API Docs en Drupal

El API Catalog permite hacer la carga y administración completa de la documentación a través del portal de administración de Drupal. Como internamente la gestión de los API Docs se realiza mediante llamadas REST, este proceso se puede automatizar. Una forma de sería mediante el desarrollo de un artefacto, Java por ejemplo, que encapsule el procedimiento para cada operación que realicemos sobre la documentación. Esto permite que con una ejecución del artefacto se realicen todos pasos necesarios de forma automática hasta tener nuestra documentación creada, actualizada o borrada.

En el momento de crear la documentación es cuando se asocia toda la información y los atributos personalizados, que servirán para poder filtrar y ordenar nuestras API Docs en el portal. Una forma de unificar toda esta información es añadiendo campos custom en la definición OpenApi, mediante la nomenclatura “x-{{atributo}}“. Un ejemplo podría ser x-category, donde indicamos la categoría a la que pertenece la API.

De esta forma, el artefacto puede extraer toda la información relacionada con la documentación de un único punto, facilitando las tareas posteriores de automatización.

Para automatizar la integración de la documentación con el API Catalog se pueden utilizar procesos de CI/CD facilitando la subida y gestión de estos API Docs.

El primer paso es utilizar un repositorio para almacenar la definición OpenAPI, dónde poder registrar todos los cambios y mantener en paralelo diferentes versiones y entornos. Conectado a este repositorio habrá una herramienta de integración que, mediante pipelines, se encargará de obtener la información necesaria para este flujo (entorno, usuario, contraseña, definición de la API…), ejecutar diferentes comandos y llamar al artefacto Java que incluye las llamadas a la API REST para dar de alta nuestra API. La llamada al artefacto se deberá parametrizar para, por ejemplo, indicar la operación que se quiera realizar (carga o modificación), el usuario y contraseña de Drupal o la ubicación del API Doc a cargar.

Una vez terminado este proceso la operación realizada sobre el API Docs habrá sido completada y se podrán comprobar los cambios en el portal de Drupal.

 

 

 

Tags

API
He leído y acepto la política de privacidad
Acepto recibir emails sobre actividades de recruiting NTT DATA