Cómo actualizar las API del portal para desarrolladores de Apigee

Introducción

Apigeo es una plataforma de administración de API que ofrece un portal de desarrolladores integrado para documentar puntos finales expuestos en los proxies de API. Esto permite a los desarrolladores interactuar fácilmente con una API y familiarizarse sin demasiada complejidad.

Todas las API están sujetas a cambios y, por lo tanto, el Portal para desarrolladores de Apigee debe cambiar para reflejar estas actualizaciones. Sin embargo, la actualización manual de la especificación API se convierte rápidamente en una tarea compleja.

Este artículo explica cómo automatizar el proceso de actualización de las API en Apigee.

Requisitos previos

• Portal para desarrolladores de Apigee

Actualización automática de las API del portal para desarrolladores de Apigee

Se necesitan tres cosas para que aparezca una especificación de API en el portal para desarrolladores de Apigee:

• La especificación API abierta , denominado archivo de especificaciones para abreviar. En nuestro caso, estamos usando la clásica tienda de mascotas.
• Un producto API – esta es una colección de API. Dado que Apigee Developer Portal funciona con ellos, crearemos uno para mostrar nuestras API. Para fines de demostración, nuestro producto API solo tendrá una API.
• Un portal de desarrolladores existente para publicar o actualizar el Producto API y la especificación.

Las siguientes secciones explican cómo automatizar el proceso de actualización de las API en Apigee.

Paso 1:Subir una especificación API

Actualmente, Apigee no proporciona ningún medio para cargar una especificación de API a través de la API de administración. Usa la interfaz de usuario de Apigee para agregar o actualizar las especificaciones de la API.

1. Seleccione Importar archivo opción para importar la especificación de Pet Store. Tenga Chrome DevTools (o equivalente) abierto mientras lo hace.

2. Debería ver la especificación API (en este ejemplo, 'petshop') en la lista, como en la imagen a continuación.

3. La especificación API se cargó correctamente. Veamos qué sucedió en segundo plano refiriéndose a la Red pestaña en Chrome DevTools.

Como máximo, se necesitan tres llamadas a la API para agregar una especificación de API:

• POST
• PUT
• GET

Llamadas API POST, PUT y GET

A continuación se muestra la primera llamada a la API:

POST https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc

{
  "folder": "173137",
  "kind": "Doc",
  "name": "petstore"
}

• folder :El ID de la carpeta de especificaciones de su organización. Esto siempre será igual ya que cada organización tiene una carpeta de especificaciones y nunca cambia.
• kind :En este caso siempre será Doc ya que estamos subiendo un documento.
• name :El nombre de la especificación API. Aunque no se aplica, use un nombre único; de lo contrario, puede resultar confuso al ver las especificaciones de la API.

El resultado de esta llamada es la creación de una especificación API vacía con el nombre especificado. La respuesta esperada de Apigee es la siguiente:

{
	"id": "299536",
	"kind": "Doc",
	"name": "petstore",
	"created": "2020-06-05T13:24:07.977Z",
	"creator": "/orgs/lukeb-eval",
	"modified": "2020-06-05T13:24:07.977Z",
	"permissions": null,
	"self": "/organizations/lukeb-eval/specs/doc/299536",
	"content": "/organizations/lukeb-eval/specs/doc/299536/content",
	"contents": null,
	"folder": "/organizations/lukeb-eval/specs/folder/173137",
	"folderId": "173137",
	"body": null,
	"trashed": false
}

Tome nota del id . Lo usará en la siguiente llamada para decirle a Apigee en qué archivo debemos colocar nuestro contenido:

PUT https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc/299536/content

El cuerpo de la solicitud para esta llamada es toda la especificación de API YAML. Como respuesta, Apigee responderá con un 200 OK , lo que indica que la especificación API se cargó con éxito.

La última llamada es:

GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home

Produce la siguiente respuesta:

{
	"id": "173137",
	"kind": "Folder",
	"name": "/orgs/lukeb-eval root",
	"created": "2019-06-06T07:39:58.805Z",
	"creator": "/orgs/lukeb-eval",
	"modified": "2019-06-06T07:39:58.805Z",
	"permissions": null,
	"self": "/organizations/lukeb-eval/specs/folder/173137",
	"content": null,
	"contents": [{
		"id": "299536",
		"kind": "Doc",
		"name": "petstore",
		"created": "2020-06-05T13:24:07.977Z",
		"creator": "/orgs/lukeb-eval",
		"modified": "2020-06-05T13:24:08.740Z",
		"permissions": null,
		"self": "/organizations/lukeb-eval/specs/doc/299536",
		"content": "/organizations/lukeb-eval/specs/doc/299536/content",
		"contents": null,
		"folder": "/organizations/lukeb-eval/specs/folder/173137",
		"folderId": "173137",
		"body": null,
		"trashed": false
	}],
	"folder": null,
	"folderId": null,
	"body": null,
	"trashed": false
}

En este punto, sabemos que los archivos de especificaciones están disponibles en nuestra organización. Esta es la última llamada ejecutada porque Apigee necesita actualizar la interfaz de usuario para mostrar las especificaciones más recientes después de agregar una nueva.

Esta llamada también se ejecuta si solo abrimos las Specs pestaña en Apigee.

Habiendo pasado por las solicitudes HTTP, ahora podemos automatizar la creación o actualización de una especificación:

• GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home – Esto nos proporciona el folderId . Lo necesitamos para la llamada posterior. También indica si la especificación debe crearse o actualizarse, dependiendo de si ya existe.
• POST https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc – Si la especificación no existe, ejecutamos esta llamada para crear un archivo vacío.
• PUT https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc/299536/content – Complete la especificación con la información más reciente. Dependiendo de si se trata de una solicitud de creación o de actualización, el id de la especificación se puede recuperar de los pasos 1 o 2.

Estos pasos se reflejan en nuestro script de automatización upload_spec.py . Este script requiere los siguientes argumentos para ejecutarse correctamente:

• name – El nombre de la especificación que se cargará en Apigee. Si no es único, se actualizará la especificación con el mismo nombre en Apigee.
• file – La ruta del archivo de especificaciones en su máquina.
• org – El nombre de la organización en Apigee. https://apigee.com/organizations/johnd-eval/proxies tiene el nombre de la organización johnd-eval .
• username – El nombre de usuario del usuario de Apigee que usa la secuencia de comandos para obtener un token de acceso. Este token de acceso se usa para todas las llamadas REST ejecutadas por el script. El access_token caduca cada 12 horas. Por lo general, aquí se utiliza un usuario de automatización dedicado.
• password – La contraseña del nombre de usuario mencionado anteriormente.

Para crear o actualizar la especificación para el ejemplo discutido anteriormente, use:

upload_spec.py --name petstore --file petstore.yaml --org lukeb-eval --username $APIGEE_USER --password $APIGEE_PASSWORD

Un resultado exitoso típico, tomado de nuestra canalización de automatización, sería el siguiente:

Paso 2:Subir un producto API

En nuestro esfuerzo de automatización, creamos upload_product.py , que aprovecha la API de administración de Apigee para crear o actualizar un producto de API.

Se requieren los siguientes argumentos para que el script se ejecute correctamente:

• file – Un archivo JSON que representa el Producto API que se va a crear. Puede encontrar un ejemplo de cómo crearlo en la sección Crear producto de API o Actualizar producto de API de la documentación de la API de administración de Apigee. El nombre siempre es obligatorio en el archivo JSON, ya que se utiliza para verificar si el Producto API existe o no. Si el producto API existe, se actualiza con el nuevo archivo JSON.
• org – El nombre de la organización en Apigee.
• username – El nombre de usuario del usuario de Apigee que usa la secuencia de comandos para obtener un token de acceso.
• password – La contraseña del nombre de usuario mencionado anteriormente.

Se puede ejecutar de la siguiente manera:

upload_api_product.py --file product_settings.json --org lukeb-eval --username $APIGEE_USER --password $APIGEE_PASSWORD

Un resultado exitoso típico, tomado de nuestra canalización de automatización, sería el siguiente:

Paso 3:Subir una especificación de API al Portal de desarrolladores

Actualizar una especificación de API no significa que el Portal para desarrolladores de Apigee muestre automáticamente la más reciente, y Apigee no ofrece esto a través de su API de administración.

Esto se puede hacer manualmente a través de la interfaz de usuario, por lo que debemos investigar qué llamadas a la API se utilizan para crear o actualizar la documentación de la API en el Portal para desarrolladores.

1. En las API de su portal seleccionado en Apigee, haga clic en +API botón:

2. Seleccione el Producto API y la especificación API. Finalmente, agregue un nombre y una descripción para la API y haga clic en Finalizar .

3. Presionando el botón Finalizar El botón solicita la siguiente llamada HTTP:

POST https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs

{
	"title": "Pet Store",
	"description": "",
	"edgeAPIProductName": "Pet Store",
	"visibility": true,
	"anonAllowed": true,
	"requireCallbackUrl": false,
	"specId": "petstore",
	"specContent": "299536"
}

4. Para mostrar la especificación de la API en el portal, necesita los siguientes parámetros:

• edgeAPIProductName – El nombre del producto API creado anteriormente.
• specId – El nombre de la especificación creada anteriormente.
• specContent – El ID de archivo de la especificación creada anteriormente.

Confusamente, el specId es en realidad el nombre de la especificación y Apigee no impone su singularidad. En nuestro script de automatización, asumimos que la especificación tiene un nombre único y esto ayudará a recuperar el specContent a través del specId más adelante.

Consideremos qué hace la interfaz de usuario de Apigee cuando cambia una especificación. Si se actualizan las especificaciones de la tienda de mascotas, aparecerá lo siguiente en la pantalla de API en el Portal para desarrolladores:

Al hacer clic en Administrar instantánea de especificaciones imagen amarilla a la derecha, obtenemos la siguiente pantalla:

Haz clic en Actualizar instantánea. . Eso actualiza el Portal para desarrolladores con las últimas especificaciones.

Automatización de solicitudes de API

Para automatizar el proceso, necesitamos tres solicitudes de API:

GET https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs

El primero, produce la siguiente respuesta:

{
	"status": "success",
	"message": "all visible apidocs returned",
	"data": [{
		"id": 57782,
		"siteId": "lukeb-eval-portal",
		"title": "Pet Store",
		"description": "Pet Store Description",
		"visibility": true,
		"enrollment": null,
		"apiId": "pet-store",
		"edgeAPIProductName": "Pet Store",
		"specId": "petstore",
		"specContent": "299536",
		"specTitle": null,
		"snapshotExists": true,
		"snapshotModified": 1591371293000,
		"modified": 1591371290000,
		"anonAllowed": true,
		"imageUrl": null,
		"snapshotState": "OK_DOCSTORE",
		"requireCallbackUrl": false,
		"categoryIds": [],
		"productExists": true,
		"specModified": null,
		"snapshotOutdated": false,
		"snapshotSourceMissing": false
	}],
	"request_id": "1309320113",
	"error_code": null
}

Desde una perspectiva de automatización, esta solicitud le proporciona la identificación del portal de desarrolladores y enumera todas las especificaciones en el portal.

Después de obtener el ID del portal, necesitamos la siguiente llamada a la API:

PUT https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs/57782

{
	"specId": "petstore",
	"imageUrl": null,
	"visibility": true,
	"anonAllowed": true,
	"description": "Pet Store Description"
}

La llamada mencionada anteriormente se utiliza para confirmar la configuración básica de la API en el portal. El DNI 57782 al final de la URL de solicitud se encuentra el ID del Portal para desarrolladores.

Al finalizar, se ejecuta otra solicitud:

PUT https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs/57782/snapshot

Esta solicitud no tiene cuerpo e indica al Portal del desarrollador que muestre las especificaciones más recientes.

Con toda esta información, ahora podemos automatizar la implementación de especificaciones del portal de la siguiente manera:

1. Usa GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home para asegurarnos de que existe la especificación que queremos mostrar.

2. Incluya GET https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs para obtener el ID del portal y verificar si necesitamos crear o actualizar la especificación en el portal.

• Si necesita crear:

POST https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs

• Si necesita actualizar:

PUT https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs/57782

PUT https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs/57782/snapshot

A tal efecto, el upload_portal_documentation.py Se creó el script de automatización. Esto necesita los siguientes parámetros:

• file – Archivo JSON que representa la Documentación del Portal API que se creará. Un ejemplo de JSON se muestra anteriormente en esta publicación. Desde orgname y specId se proporcionan como parámetros, no deben formar parte del archivo JSON, de lo contrario, se sobrescribirán. specContent se recupera de specId proporcionado, ya que estamos trabajando bajo la premisa de que un nombre de especificación siempre será único.
• portal – Nombre completo del portal donde queremos crear la documentación. p.ej. Si se accede a un portal a través de https://johnd-eval-test.apigee.io, el nombre completo del portal es johnd-eval-test .
• org – Igual que en upload_spec.py .
• username – Igual que en upload_spec.py .
• password – Igual que en upload_spec.py .

Se puede ejecutar de la siguiente manera:

upload_portal_documentation.py --file portal_documentation_setup.json --org lukeb-eval --spec_name petstore --portal portal --username $APIGEE_USER --password $APIGEE_PASSWORD

Un resultado exitoso típico, tomado de nuestra canalización de automatización, sería el siguiente:

Paso 4:Integración de canalización de CI/CD

Tenemos estos scripts en una imagen de Docker, por lo que es muy fácil importarlos y ejecutarlos en su canalización de CI/CD.

Tomemos GitLab por ejemplo:

apigee-spec-deploy:
  image: ghcr.io/phoenixnap/apigee-automation:v1.0.0
  stage: spec-deploy
  variables:
    SPEC_NAME: petstore
    SPEC_PATH: petstore.yaml
    APIGEE_PRODUCT: product.json
    APIGEE_PORTAL_DOC: portal_documentation.json
  script:
    - /automation/upload_spec.py --name $SPEC_NAME --file $SPEC_PATH --org $ORG_NAME --username $APIGEE_USER --password $APIGEE_PASSWORD
    - /automation/upload_api_product.py --file $APIGEE_PRODUCT --org $ORG_NAME --username $APIGEE_USER --password $APIGEE_PASSWORD
    - /automation/upload_portal_documentation.py --file $APIGEE_PORTAL_DOC --org $ORG_NAME --spec_name $SPEC_NAME --portal $APIGEE_PORTAL --username $APIGEE_USER --password $APIGEE_PASSWORD

Hemos creado un trabajo de canalización llamado apigee-spec-deploy , que extrae la imagen apigee-automation de GitHub Packages y ejecuta las tres secuencias de comandos de Python que discutimos aquí con los parámetros necesarios.

El trabajo de GitLab dejará de ejecutarse si falla algún script. Si eso ocurre, se proporciona un error detallado en la salida. Esto garantiza que siempre que se ejecute un script, estará disponible toda la información que necesita de los scripts anteriores.