Comment mettre à jour les API du portail des développeurs Apigee

Présentation

Apigee est une plate-forme de gestion d'API qui offre un portail de développeur intégré pour documenter les points de terminaison exposés dans les proxys d'API. Cela permet aux développeurs d'interagir facilement avec une API et de se familiariser sans trop de complexité.

Toutes les API sont susceptibles d'être modifiées et, par conséquent, le portail des développeurs Apigee doit être modifié pour refléter ces mises à jour. Cependant, la mise à jour manuelle de la spécification de l'API devient rapidement une tâche complexe.

Cet article explique comment automatiser le processus de mise à jour des API dans Apigee.

Prérequis

Portail des développeurs Apigee

Mise à jour automatisée des API du portail des développeurs Apigee

Trois éléments sont nécessaires pour qu'une spécification d'API apparaisse dans le portail des développeurs Apigee :

La spécification Open API , appelé fichier de spécifications en abrégé. Dans notre cas, nous utilisons le Pet Store classique.
Un produit d'API – il s'agit d'une collection d'API. Étant donné que le portail des développeurs Apigee fonctionne avec eux, nous allons en créer un pour afficher nos API. À des fins de démonstration, notre produit API n'aura qu'une seule API.
Un portail de développeur existant pour publier ou mettre à jour le produit et les spécifications de l'API.

Les sections ci-dessous expliquent comment automatiser le processus de mise à jour des API sur Apigee.

Étape 1 :Importer une spécification d'API

Actuellement, Apigee ne fournit aucun moyen d'importer une spécification d'API via l'API Admin. Utilisez l'interface utilisateur d'Apigee pour ajouter ou mettre à jour les spécifications de l'API.

1. Sélectionnez le fichier d'importation possibilité d'importer la spécification Pet Store. Ouvrez Chrome DevTools (ou équivalent) pendant cette opération.

2. Vous devriez voir la spécification de l'API (dans cet exemple, "petshop") répertoriée, comme dans l'image ci-dessous.

3. La spécification de l'API a été téléchargée avec succès. Voyons ce qui s'est passé en arrière-plan en nous référant au réseau onglet dans Chrome DevTools.

Au maximum, trois appels d'API sont nécessaires pour ajouter une spécification d'API :

POST
PUT
GET

Appels API POST, PUT et GET

Ci-dessous le premier appel d'API :

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

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

folder :ID du dossier de spécifications de votre organisation. Ce sera toujours le même puisque chaque organisation a un dossier de spécifications et il ne change jamais.
kind :Dans ce cas, ce sera toujours Doc puisque nous téléchargeons un document.
name :nom de la spécification d'API. Bien qu'il ne soit pas appliqué, utilisez un nom unique, sinon cela peut prêter à confusion lors de l'affichage des spécifications de l'API.

Le résultat de cet appel est la création d'une spécification d'API vide avec le nom spécifié. La réponse attendue d'Apigee est la suivante :

{
	"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
}

Notez l'id . Vous l'utiliserez dans l'appel suivant pour indiquer à Apigee dans quel fichier nous devons placer notre contenu :

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

Le corps de la requête pour cet appel est l'intégralité de la spécification d'API YAML. En réponse, Apigee répondra par un 200 OK , signalant que la spécification d'API a été téléchargée avec succès.

Le dernier appel est :

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

Il produit la réponse suivante :

{
	"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
}

À ce stade, nous savons que les fichiers de spécifications sont disponibles dans notre organisation. Il s'agit du dernier appel exécuté, car Apigee doit mettre à jour l'interface utilisateur pour afficher les dernières spécifications après en avoir ajouté une nouvelle.

Cet appel est également exécuté si nous ouvrons simplement les Specs onglet dans Apigee.

Après avoir parcouru les requêtes HTTP, nous sommes désormais en mesure d'automatiser la création ou la mise à jour d'une spécification :

GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home – Cela nous fournit le folderId . Nous en avons besoin pour l'appel suivant. Il indique également si la spécification doit être créée ou mise à jour, selon qu'elle existe déjà.
POST https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc – Si la spécification n'existe pas, nous exécutons cet appel pour créer un fichier vide.
PUT https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc/299536/content – Remplissez la spécification avec les dernières informations. Selon qu'il s'agit d'une demande de création ou de mise à jour, l'id de la spécification peut être récupérée à partir des étapes 1 ou 2.

Ces étapes sont reflétées dans notre script d'automatisation upload_spec.py . Ce script nécessite les arguments suivants pour s'exécuter correctement :

name – Le nom de la spécification qui sera importée dans Apigee. S'il n'est pas unique, la spécification portant le même nom dans Apigee sera mise à jour.
file – Le chemin du fichier spec sur votre machine.
org – Le nom de l'organisation dans Apigee. https://apigee.com/organizations/johnd-eval/proxies a le nom d'organisation johnd-eval .
username – Le nom d'utilisateur de l'utilisateur Apigee utilisé par le script pour récupérer un jeton d'accès. Ce jeton d'accès est utilisé pour tous les appels REST exécutés par le script. Le jeton d'accès expire toutes les 12 heures. Habituellement, un utilisateur d'automatisation dédié est utilisé ici.
password – Le mot de passe pour le nom d'utilisateur mentionné ci-dessus.

Pour créer ou mettre à jour la spécification de l'exemple décrit ci-dessus, utilisez :

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

Un résultat réussi typique, tiré de notre pipeline d'automatisation, serait le suivant :

Étape 2 :Importer un produit d'API

Dans notre effort d'automatisation, nous avons créé upload_product.py , qui exploite l'API Apigee Management pour créer ou mettre à jour un produit d'API.

Les arguments suivants sont requis pour que le script s'exécute correctement :

file – Un fichier JSON représentant le Produit API à créer. Vous trouverez un exemple de création dans la section Créer un produit d'API ou Mettre à jour un produit d'API de la documentation de l'API de gestion Apigee. Le nom est toujours obligatoire dans le fichier JSON car il est utilisé pour vérifier si le produit API existe ou non. Si le produit API existe, il est mis à jour avec le nouveau fichier JSON.
org – Le nom de l'organisation dans Apigee.
username – Le nom d'utilisateur de l'utilisateur Apigee utilisé par le script pour récupérer un jeton d'accès.
password – Le mot de passe du nom d'utilisateur mentionné ci-dessus.

Il peut être exécuté comme suit :

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

Un résultat réussi typique, tiré de notre pipeline d'automatisation, serait le suivant :

Étape 3 :Importation d'une spécification d'API sur le portail des développeurs

La mise à jour d'une spécification d'API ne signifie pas que le portail des développeurs Apigee affichera automatiquement la plus récente, et Apigee ne propose pas cela via son API de gestion.

Cela peut être fait manuellement via l'interface utilisateur, nous devons donc rechercher quels appels d'API sont utilisés pour créer ou mettre à jour la documentation de l'API sur le portail des développeurs.

1. Dans les API de votre portail sélectionné dans Apigee, cliquez sur + API bouton :

2. Sélectionnez le produit API et la spécification API. Enfin, ajoutez un nom et une description pour l'API, puis cliquez sur Terminer .

3. Appuyez sur Terminer le bouton invite l'appel HTTP suivant :

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. Pour afficher la spécification de l'API dans le portail, vous avez besoin des paramètres suivants :

edgeAPIProductName – Le nom du produit API créé précédemment.
specId – Le nom de la spécification créée précédemment.
specContent – L'ID de fichier de la spécification précédemment créée.

De manière confuse, le specId est en fait le nom de la spécification et son caractère unique n'est pas appliqué par Apigee. Dans notre script d'automatisation, nous supposons que la spécification porte un nom unique, ce qui aidera à récupérer le specContent via le specId plus loin.

Examinons ce que fait l'interface utilisateur d'Apigee lorsqu'une spécification change. Si la spécification Pet Store est mise à jour, les éléments suivants s'afficheront sur l'écran des API du portail des développeurs :

En cliquant sur Gérer l'instantané des spécifications image jaune à droite, on obtient l'écran suivant :

Cliquez sur Mettre à jour l'instantané . Cela met à jour le portail des développeurs avec les dernières spécifications.

Automatisation des requêtes API

Pour automatiser le processus, nous avons besoin de trois requêtes API :

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

Le premier produit la réponse suivante :

{
	"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
}

Du point de vue de l'automatisation, cette requête vous fournit l'ID du portail de développeur et répertorie toutes les spécifications sur le portail.

Après avoir obtenu l'ID du portail, nous avons besoin de l'appel d'API suivant :

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

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

L'appel mentionné ci-dessus est utilisé pour confirmer la configuration de base de l'API sur le portail. L'identifiant 57782 à la fin de l'URL de la demande se trouve l'ID du portail de développeur.

Une fois terminé, une autre requête est exécutée :

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

Cette requête n'a pas de corps et demande au portail de développeur d'afficher la dernière spécification.

Grâce à toutes ces informations, nous sommes désormais en mesure d'automatiser le déploiement de la spécification de portail comme suit :

1. Utilisez GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home pour s'assurer que la spécification que nous voulons afficher existe.

2. Incluez GET https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs pour obtenir l'ID du portail et vérifier si nous devons créer ou mettre à jour la spécification dans le portail.

Si vous devez créer :

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

Si vous devez mettre à jour :

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

À cet effet, le upload_portal_documentation.py script d'automatisation a été créé. Cela nécessite les paramètres suivants :

file – Fichier JSON représentant la documentation API Portal à créer. Un exemple du JSON est montré précédemment dans ce post. Depuis orgname et specId sont fournis en tant que paramètres, ils ne doivent pas faire partie du fichier JSON, sinon ils seront écrasés. specContent est extrait du specId fourni, puisque nous partons du principe qu'un nom de spécification sera toujours unique.
portal – Nom complet du portail où nous voulons créer la documentation. par exemple. Si un portail est accessible via https://johnd-eval-test.apigee.io, le nom complet du portail est johnd-eval-test .
org – Identique à upload_spec.py .
username – Identique à upload_spec.py .
password – Identique à upload_spec.py .

Il peut être exécuté comme suit :

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

Un résultat réussi typique, tiré de notre pipeline d'automatisation, serait le suivant :

Étape 4 :Intégration du pipeline CI/CD

Nous avons ces scripts dans une image Docker, il est donc très facile de les importer et de les exécuter dans votre pipeline CI/CD.

Prenons GitLab par exemple :

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

Nous avons créé une tâche de pipeline appelée apigee-spec-deploy , qui extrait l'image apigee-automation à partir de GitHub Packages, et exécute les trois scripts python dont nous avons parlé ici avec les paramètres nécessaires.

Le travail GitLab cessera de s'exécuter si un script échoue. Si cela se produit, une erreur détaillée est fournie dans la sortie. Cela garantit que chaque fois qu'un script est exécuté, toutes les informations dont il a besoin des scripts précédents seront disponibles.