So aktualisieren Sie Apigee Developer Portal-APIs

Einführung

Apigee ist eine API-Verwaltungsplattform, die ein integriertes Entwicklerportal zum Dokumentieren exponierter Endpunkte in den API-Proxys bietet. Dadurch können Entwickler einfach mit einer API interagieren und sich ohne allzu große Komplexität damit vertraut machen.

Alle APIs können sich ändern, und daher muss das Apigee-Entwicklerportal geändert werden, um diese Aktualisierungen widerzuspiegeln. Die manuelle Aktualisierung der API-Spezifikation wird jedoch schnell zu einer komplexen Aufgabe.

In diesem Artikel wird erläutert, wie Sie den Prozess der Aktualisierung von APIs in Apigee automatisieren.

Voraussetzungen

• Apigee-Entwicklerportal

Automatisierte Aktualisierung von APIs des Apigee-Entwicklerportals

Drei Dinge sind erforderlich, damit eine API-Spezifikation im Apigee-Entwicklerportal angezeigt wird:

• Die Open API-Spezifikation , kurz Spec-Datei genannt. In unserem Fall verwenden wir die klassische Tierhandlung.
• Ein API-Produkt – Dies ist eine Sammlung von APIs. Da das Apigee-Entwicklerportal mit ihnen arbeitet, werden wir eines erstellen, um unsere APIs anzuzeigen. Zu Demonstrationszwecken wird unser API-Produkt nur eine API haben.
• Ein vorhandenes Entwicklerportal um das API-Produkt und die Spezifikation zu veröffentlichen oder zu aktualisieren.

In den folgenden Abschnitten wird erläutert, wie Sie den Prozess der Aktualisierung von APIs in Apigee automatisieren.

Schritt 1:Hochladen einer API-Spezifikation

Derzeit bietet Apigee keine Möglichkeit, eine API-Spezifikation über die Admin-API hochzuladen. Verwenden Sie die Apigee-Benutzeroberfläche, um API-Spezifikationen hinzuzufügen oder zu aktualisieren.

1. Wählen Sie die Datei importieren aus Option zum Importieren der Pet Store-Spezifikation. Lassen Sie dabei Chrome DevTools (oder gleichwertig) geöffnet sein.

2. Sie sollten die API-Spezifikation (in diesem Beispiel „Petshop“) sehen, wie im Bild unten.

3. Die API-Spezifikation wurde erfolgreich hochgeladen. Sehen wir uns an, was im Hintergrund passiert, indem wir uns auf das Netzwerk beziehen Registerkarte in Chrome DevTools.

Zum Hinzufügen einer API-Spezifikation sind höchstens drei API-Aufrufe erforderlich:

• POST
• PUT
• GET

API-Aufrufe POST, PUT und GET

Unten ist der erste API-Aufruf:

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

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

• folder :Die ID des Spezifikationsordners Ihrer Organisation. Dies wird immer gleich sein, da jede Organisation einen Spezifikationsordner hat und dieser sich nie ändert.
• kind :In diesem Fall ist es immer Doc da wir gerade ein Dokument hochladen.
• name :Der Name der API-Spezifikation. Obwohl es nicht erzwungen wird, verwenden Sie einen eindeutigen Namen, da es sonst beim Anzeigen der API-Spezifikationen verwirrend werden kann.

Das Ergebnis dieses Aufrufs ist die Erstellung einer leeren API-Spezifikation mit dem angegebenen Namen. Die erwartete Antwort von Apigee lautet wie folgt:

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

Notieren Sie sich die id . Sie werden es im folgenden Aufruf verwenden, um Apigee mitzuteilen, in welche Datei wir unseren Inhalt einfügen müssen:

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

Der Anforderungstext für diesen Aufruf ist die gesamte API-Spezifikation YAML. Als Antwort antwortet Apigee mit 200 OK , signalisiert, dass die API-Spezifikation erfolgreich hochgeladen wurde.

Der letzte Aufruf lautet:

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

Es erzeugt die folgende Antwort:

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

An diesem Punkt wissen wir, dass die Spezifikationsdateien in unserer Organisation verfügbar sind. Dies ist der letzte ausgeführte Aufruf, da Apigee die Benutzeroberfläche aktualisieren muss, um die neuesten Spezifikationen anzuzeigen, nachdem eine neue hinzugefügt wurde.

Dieser Aufruf wird auch ausgeführt, wenn wir einfach die Specs öffnen Tab in Apigee.

Nachdem wir die HTTP-Anforderungen durchlaufen haben, sind wir jetzt in der Lage, die Erstellung oder Aktualisierung einer Spezifikation zu automatisieren:

• GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home – Dadurch erhalten wir die folderId . Diese benötigen wir für den anschließenden Anruf. Es gibt auch an, ob die Spezifikation erstellt oder aktualisiert werden muss, je nachdem, ob sie bereits vorhanden ist.
• POST https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc – Wenn die Spezifikation nicht existiert, führen wir diesen Aufruf aus, um eine leere Datei zu erstellen.
• PUT https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc/299536/content – Füllen Sie die Spezifikation mit den neuesten Informationen aus. Je nachdem, ob es sich um eine Erstellungs- oder Aktualisierungsanforderung handelte, wird die id der Spezifikation können aus den Schritten 1 oder 2 abgerufen werden.

Diese Schritte spiegeln sich in unserem Automatisierungsskript upload_spec.py wider . Dieses Skript erfordert die folgenden Argumente, um erfolgreich ausgeführt zu werden:

• name – Der Name der Spezifikation, die in Apigee hochgeladen wird. Wenn dies nicht eindeutig ist, wird die Spezifikation mit demselben Namen in Apigee aktualisiert.
• file – Der Pfad der Spezifikationsdatei auf Ihrem Computer.
• org – Der Name der Organisation in Apigee. https://apigee.com/organizations/johnd-eval/proxys hat den Organisationsnamen johnd-eval .
• username – Der Benutzername des Apigee-Benutzers, den das Skript verwendet, um ein Zugriffstoken abzurufen. Dieses Zugriffstoken wird für alle vom Skript ausgeführten REST-Aufrufe verwendet. Das access_token läuft alle 12 Stunden ab. Normalerweise wird hier ein dedizierter Automatisierungsbenutzer verwendet.
• password – Das Passwort für den oben genannten Benutzernamen.

Um die Spezifikation für das oben beschriebene Beispiel zu erstellen oder zu aktualisieren, verwenden Sie:

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

Ein typisches erfolgreiches Ergebnis aus unserer Automatisierungspipeline wäre wie folgt:

Schritt 2:Hochladen eines API-Produkts

Bei unseren Automatisierungsbemühungen haben wir upload_product.py erstellt , das die Apigee Management API nutzt, um ein API-Produkt zu erstellen oder zu aktualisieren.

Die folgenden Argumente sind erforderlich, damit das Skript erfolgreich ausgeführt werden kann:

• file – Eine JSON-Datei, die das zu erstellende API-Produkt darstellt. Ein Beispiel für die Erstellung finden Sie im Abschnitt API-Produkt erstellen oder API-Produkt aktualisieren der Apigee Management API-Dokumentation. Der Name ist in der JSON-Datei immer obligatorisch, da er verwendet wird, um zu prüfen, ob das API-Produkt vorhanden ist oder nicht. Wenn das API-Produkt vorhanden ist, wird es mit der neuen JSON-Datei aktualisiert.
• org – Der Name der Organisation in Apigee.
• username – Der Benutzername des Apigee-Benutzers, den das Skript zum Abrufen eines Zugriffstokens verwendet.
• password – Das Passwort für den oben genannten Benutzernamen.

Es kann wie folgt ausgeführt werden:

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

Ein typisches erfolgreiches Ergebnis aus unserer Automatisierungspipeline wäre wie folgt:

Schritt 3:Hochladen einer API-Spezifikation in das Entwicklerportal

Das Aktualisieren einer API-Spezifikation bedeutet nicht, dass das Apigee-Entwicklerportal automatisch die neueste anzeigt, und Apigee bietet dies nicht über seine Verwaltungs-API an.

Dies kann manuell über die Benutzeroberfläche erfolgen, daher müssen wir untersuchen, welche API-Aufrufe verwendet werden, um die API-Dokumentation im Entwicklerportal zu erstellen oder zu aktualisieren.

1. In den APIs Abschnitt Ihres ausgewählten Portals in Apigee auf +API Schaltfläche:

2. Wählen Sie das API-Produkt und die API-Spezifikation aus. Fügen Sie abschließend einen Namen und eine Beschreibung für die API hinzu und klicken Sie auf Fertig stellen .

3. Klicken Sie auf Fertig Schaltfläche fordert den folgenden HTTP-Aufruf auf:

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. Um die API-Spezifikation im Portal anzuzeigen, benötigen Sie die folgenden Parameter:

• edgeAPIProductName – Der Name des zuvor erstellten API-Produkts.
• specId – Der Name der zuvor erstellten Spezifikation.
• specContent – Die Datei-ID der zuvor erstellten Spezifikation.

Verwirrenderweise die specId ist eigentlich der Name der Spezifikation und ihre Eindeutigkeit wird von Apigee nicht erzwungen. In unserem Automatisierungsskript gehen wir davon aus, dass die Spezifikation eindeutig benannt ist, und dies hilft beim Abrufen des specContent durch die specId weiter.

Sehen wir uns an, was die Apigee-Benutzeroberfläche tut, wenn sich eine Spezifikation ändert. Wenn die Pet Store-Spezifikation aktualisiert wird, wird Folgendes auf dem APIs-Bildschirm im Entwicklerportal angezeigt:

Durch Klicken auf Spezifikations-Snapshot verwalten gelbes Bild auf der rechten Seite erhalten wir den folgenden Bildschirm:

Klicken Sie auf Snapshot aktualisieren . Dadurch wird das Entwicklerportal mit der neuesten Spezifikation aktualisiert.

API-Anfragen automatisieren

Um den Prozess zu automatisieren, benötigen wir drei API-Anforderungen:

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

Die erste erzeugt die folgende Antwort:

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

Aus Sicht der Automatisierung liefert Ihnen diese Anfrage die ID des Entwicklerportals und listet alle Spezifikationen im Portal auf.

Nachdem wir die Portal-ID erhalten haben, benötigen wir den folgenden API-Aufruf:

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

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

Der oben genannte Aufruf dient dazu, die Grundeinstellung der API auf dem Portal zu bestätigen. Die ID 57782 Am Ende der Anforderungs-URL steht die ID des Entwicklerportals.

Nach Abschluss wird eine weitere Anfrage ausgeführt:

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

Diese Anfrage hat keinen Text und weist das Entwicklerportal an, die neueste Spezifikation anzuzeigen.

Mit all diesen Informationen sind wir jetzt in der Lage, die Portalspezifikationsbereitstellung wie folgt zu automatisieren:

1. Verwenden Sie GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home um sicherzustellen, dass die Spezifikation, die wir anzeigen möchten, vorhanden ist.

2. Fügen Sie GET https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs hinzu um die Portal-ID zu erhalten und zu prüfen, ob wir die Spezifikation im Portal erstellen oder aktualisieren müssen.

• Wenn Sie Folgendes erstellen müssen:

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

• Wenn Sie aktualisieren müssen:

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

Dazu die upload_portal_documentation.py Automatisierungsskript wurde erstellt. Dies benötigt die folgenden Parameter:

• file – JSON-Datei, die die zu erstellende API-Portal-Dokumentation darstellt. Ein Beispiel für JSON wurde zuvor in diesem Beitrag gezeigt. Seit orgname und specId als Parameter bereitgestellt werden, sollten sie nicht Teil der JSON-Datei sein, da sie sonst überschrieben werden. specContent wird aus der specId abgerufen bereitgestellt, da wir davon ausgehen, dass ein Spezifikationsname immer eindeutig ist.
• portal – Vollständiger Name des Portals, in dem wir die Dokumentation erstellen möchten. z.B. Wenn über https://johnd-eval-test.apigee.io auf ein Portal zugegriffen wird, lautet der vollständige Name des Portals johnd-eval-test .
• org – Dasselbe wie in upload_spec.py .
• username – Dasselbe wie in upload_spec.py .
• password – Dasselbe wie in upload_spec.py .

Es kann wie folgt ausgeführt werden:

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

Ein typisches erfolgreiches Ergebnis aus unserer Automatisierungspipeline wäre wie folgt:

Schritt 4:CI/CD-Pipeline-Integration

Wir haben diese Skripte in einem Docker-Image, sodass es sehr einfach ist, sie in Ihre CI/CD-Pipeline zu importieren und auszuführen.

Nehmen wir zum Beispiel GitLab:

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

Wir haben einen Pipeline-Job namens apigee-spec-deploy erstellt , wodurch das Bild apigee-automation abgerufen wird von GitHub Packages und führt die drei Python-Skripte aus, die wir hier besprochen haben, mit den notwendigen Parametern.

Der GitLab-Job stoppt die Ausführung, wenn ein Skript fehlschlägt. In diesem Fall wird in der Ausgabe ein detaillierter Fehler bereitgestellt. Dies garantiert, dass jedes Mal, wenn ein Skript ausgeführt wird, alle Informationen verfügbar sind, die es aus den vorherigen Skripten benötigt.