APIs veröffentlichen (Originalversion)

Sie lesen gerade die Dokumentation zu Apigee Edge.
Apigee X-Dokumentation aufrufen. info

Veröffentlichen Sie APIs in Ihrem Portal, um sie App-Entwicklern zur Verfügung zu stellen, wie in den folgenden Abschnitten beschrieben.

API-Veröffentlichung

Die Veröffentlichung von APIs in Ihrem Portal erfolgt in zwei Schritten:

  1. Wählen Sie das API-Produkt aus, das Sie in Ihrem Portal veröffentlichen möchten.
  2. Sie können automatisch eine API-Referenzdokumentation aus einem Snapshot Ihrer OpenAPI-Spezifikation generieren, damit App-Entwickler Informationen zu Ihren APIs erhalten können. Weitere Informationen zu Snapshots finden Sie unter Was ist ein Snapshot einer OpenAPI-Spezifikation?

Wenn Sie eine API in Ihrem Portal veröffentlichen, werden die folgenden Aktualisierungen automatisch an Ihrem Portal vorgenommen:

  • Eine API-Referenzseite wird Ihrem Portal hinzugefügt.
    Auf der API-Referenzseite wird die API-Referenzdokumentation angezeigt, die Sie automatisch aus einem Snapshot Ihrer OpenAPI-Spezifikation generieren. Entwickler können Ihre API-Dokumentation aufrufen und auf Ausprobieren klicken, um eine API-Anfrage zu stellen und die Ausgabe anzusehen.

    Hinweis: Sie können den Inhalt dieser Seite nicht direkt bearbeiten. Er wird nicht in der Liste der Seiten in Ihrem Portal angezeigt.

  • Der Seite „APIs“ wird ein Link zur API-Referenzseite hinzugefügt.
    Die Seite „APIs“ (im Beispielportal enthalten) umfasst eine Liste aller in Ihrem Portal veröffentlichten APIs mit Links zur entsprechenden API-Referenzdokumentation mit weiteren Informationen.

    Hinweis: Sie können den Inhalt dieser Seite nicht direkt bearbeiten. Er wird nicht in der Liste der Seiten in Ihrem Portal angezeigt.

Was ist ein Snapshot einer OpenAPI-Spezifikation?

Jede OpenAPI-Spezifikation dient als „Source of Truth“ für den gesamten Lebenszyklus einer API. Die gleiche Spezifikation wird in jeder Phase des API-Lebenszyklus verwendet, von der Entwicklung über die Veröffentlichung bis hin zum Monitoring. Wenn Sie eine Spezifikation ändern, müssen Sie wissen, welche Auswirkungen die Änderungen auf Ihre API durch andere Lebenszyklusphasen haben, wie unter Was passiert, wenn ich eine Spezifikation ändere? beschrieben.

Wenn Sie Ihre API veröffentlichen, erstellen Sie einen Snapshot der OpenAPI-Spezifikation, um die API-Referenzdokumentation zu generieren. Dieser Snapshot repräsentiert eine bestimmte Version der Spezifikation im Spezifikationsspeicher. Wenn Sie die OpenAPI-Spezifikation mit dem Spezifikationseditor ändern, können Sie einen weiteren Snapshot der Spezifikation erstellen, um die neuesten Änderungen in der API-Referenzdokumentation widerzuspiegeln.

API-Proxys CORS-Unterstützung hinzufügen

Bevor Sie Ihre APIs veröffentlichen, müssen Sie Ihren API-Proxys CORS-Unterstützung hinzufügen, um clientseitige Cross-Origin-Anfragen zu unterstützen.

CORS (Cross-Origin Resource Sharing) ist ein Standardmechanismus, mit dem JavaScript XMLHttpRequest-Aufrufe (XHR), die auf einer Webseite ausgeführt werden, mit Ressourcen von Nicht-Origin-Domains interagieren können. CORS ist eine häufig implementierte Lösung für die Same-Origin-Richtlinie, die von allen Browsern durchgesetzt wird. Wenn Sie beispielsweise einen XHR-Aufruf an die Twitter API über JavaScript-Code ausführen, der in Ihrem Browser ausgeführt wird, schlägt der Aufruf fehl. Das liegt daran, dass die Domain, über die die Seite in Ihrem Browser bereitgestellt wird, nicht mit der Domain übereinstimmt, über die die Twitter API bereitgestellt wird. CORS bietet eine Lösung für dieses Problem, indem Server die Möglichkeit haben, sich für Cross-Origin Resource Sharing zu entscheiden.

Informationen zum Hinzufügen von CORS-Unterstützung zu Ihren API-Proxys vor dem Veröffentlichen der APIs finden Sie unter Einem API-Proxy CORS-Unterstützung hinzufügen.

Hinweis: Die meisten modernen Browser erzwingen CORS. Vollständige Liste der unterstützten Browser Eine ausführliche Beschreibung von CORS finden Sie in der W3C-Empfehlung zum Cross-Origin Resource Sharing.

Seite „APIs“ aufrufen

So greifen Sie auf die Seite „APIs“ zu:

  1. Wählen Sie Veröffentlichen > Portale und anschließend Ihr Portal aus.
  2. Klicken Sie auf der Startseite des Portals auf APIs.

Alternativ können Sie im Drop-down-Menü des Portals in der oberen Navigationsleiste die Option APIs auswählen.

Die Liste der APIs wird angezeigt.

API-Referenz

Wie bereits erwähnt, können Sie auf der Seite „APIs“ Folgendes tun:

API zu Ihrem Portal hinzufügen

Hinweis: Sie können Ihrem Portal maximal 100 APIs hinzufügen.

So fügen Sie Ihrem Portal eine API hinzu:

  1. Wählen Sie Veröffentlichen > Portale und anschließend Ihr Portal aus.
  2. Klicken Sie auf der Startseite des Portals auf APIs.
    Alternativ können Sie im Drop-down-Menü des Portals in der oberen Navigationsleiste die Option APIs auswählen.
  3. Klicken Sie auf + API.
    Das Dialogfeld „API-Produkt zum Portal hinzufügen“ wird angezeigt.

  4. Wählen Sie auf dem Tab „API-Produkt“ im Dialogfeld das API-Produkt aus, das Sie Ihrem Portal hinzufügen möchten.

  5. Klicke auf Weiter.

  6. Wählen Sie die Quelle für den Snapshot aus.
    Wenn Sie den im API-Produkt enthaltenen API-Proxy mit einer OpenAPI-Spezifikation erstellt haben, wählen Sie die Spezifikation aus der Drop-down-Liste aus.
    Snapshot hinzufügen

    Alternativ können Sie Folgendes auswählen:

    • Keine Spezifikation auswählen und später eine hinzufügen, nachdem die API veröffentlicht wurde, wie unter Snapshot der Spezifikation erstellen beschrieben.
    • Klicken Sie auf Andere Spezifikation auswählen, um eine neue Spezifikation auszuwählen oder hochzuladen.

  7. Klicken Sie auf das Kästchen Veröffentlicht, um die API in Ihrem Portal zu veröffentlichen. Deaktivieren Sie Veröffentlicht, wenn Sie die API noch nicht veröffentlichen möchten.
    Sie können die Einstellung später ändern, wie unter API auf dem Portal veröffentlichen oder Veröffentlichung aufheben beschrieben.

  8. Wählen Sie unter „Zielgruppe“ eine der folgenden Optionen aus, um die Zielgruppe für Ihre API zu verwalten, indem Sie den Zugriff für Folgendes zulassen:

    • Anonyme Nutzer, um allen Nutzern die Anzeige der Seite zu ermöglichen.
    • Registrierte Nutzer, um nur registrierten Nutzer die Anzeige der Seite zu ermöglichen.

    Sie können die Einstellung später ändern, wie unter Zielgruppe für eine API in Ihrem Portal verwalten beschrieben.

  9. Klicken Sie auf Beenden.

Snapshot der Spezifikation erstellen

Nach dem Veröffentlichen Ihrer API können Sie jederzeit einen neuen Snapshot der OpenAPI-Spezifikation erstellen, um die API-Referenzdokumentation zu aktualisieren, die auf dem Portal veröffentlicht wurde.

So erstellen Sie einen Snapshot der OpenAPI-Spezifikation:

  1. Wählen Sie Veröffentlichen > Portale und anschließend Ihr Portal aus.
  2. Klicken Sie auf der Startseite des Portals auf APIs.
    Alternativ können Sie im Drop-down-Menü des Portals in der oberen Navigationsleiste die Option APIs auswählen.
  3. Bewegen Sie den Mauszeiger auf die API, von der Sie einen Snapshot erstellen möchten, um die Aktionen aufzurufen.

  4. Klicken Sie auf Snapshot-Symbol.

    Hinweis: Wenn Ihr Snapshot mit der ausgewählten Quellspezifikation übereinstimmt, wird eine entsprechende Meldung angezeigt.

  5. Wählen Sie im Drop-down-Menü „Snapshot-Quelle“ eine vorhandene Spezifikation aus oder wählen Sie Andere Spezifikation auswählen aus, um eine neue Spezifikation auszuwählen oder hochzuladen, die zum Generieren der Dokumentation für die API verwendet werden soll. Alternativ können Sie Keine Spezifikation auswählen, um die aktuelle Spezifikation zu entfernen.

  6. Klicken Sie auf Snapshot aktualisieren (oder Snapshot entfernen, wenn Sie „Keine Spezifikation“ ausgewählt haben).

Die API-Referenzdokumentation wird aus der Spezifikation generiert und der API-Referenzseite hinzugefügt.

API auf dem Portal veröffentlichen oder Veröffentlichung aufheben

So veröffentlichen Sie eine API auf Ihrem Portal oder heben die Veröffentlichung auf:

  1. Wählen Sie Veröffentlichen > Portale und anschließend Ihr Portal aus.
  2. Klicken Sie auf der Startseite des Portals auf APIs.
    Alternativ können Sie im Drop-down-Menü des Portals in der oberen Navigationsleiste die Option APIs auswählen.
  3. Bewegen Sie den Mauszeiger auf die API, die Sie veröffentlichen oder deren Veröffentlichung Sie aufheben möchten.
  4. Klicken Sie auf Symbol: Einstellungen.
  5. Klicken Sie das Kästchen Aktiviert an, um die API in Ihrem Portal zu veröffentlichen. Entfernen Sie das Häkchen bei Aktiviert, um die API zu deaktivieren.
  6. Klicken Sie auf Speichern.

Zielgruppe für eine API in Ihrem Portal verwalten

Verwalten Sie die Zielgruppe für die API im Portal, indem Sie Folgendes gewähren:

  • Alle Nutzer
  • Nur registrierte Nutzer

So verwalten Sie die Zielgruppe für eine API in Ihrem Portal:

  1. Wählen Sie Veröffentlichen > Portale und anschließend dein Portal aus.
  2. Klicken Sie auf der Startseite des Portals auf APIs.
    Alternativ können Sie im Drop-down-Menü des Portals in der oberen Navigationsleiste die Option APIs auswählen.
  3. Bewegen Sie den Mauszeiger auf die API, für die Sie die Zielgruppe verwalten möchten, um die Aktionen einzublenden.
  4. Klicken Sie auf Symbol „Einstellungen“.
  5. Wählen Sie unter „Zielgruppe“ eine der folgenden Optionen aus:
    • Anonyme Nutzer, damit alle Nutzer die API sehen können.
    • Registrierte Nutzer, um nur registrierten Nutzern Zugriff auf die API zu gewähren.
  6. Klicken Sie auf Speichern.

API aus dem Portal entfernen

So entfernen Sie eine API aus dem Portal:

  1. Wählen Sie Veröffentlichen > Portale und anschließend Ihr Portal aus.
  2. Klicken Sie auf der Startseite des Portals auf APIs.
    Alternativ können Sie im Drop-down-Menü des Portals in der oberen Navigationsleiste die Option APIs auswählen.
  3. Bewegen Sie den Mauszeiger in der Liste auf die API, um das Aktionsmenü einzublenden.
  4. Klicken Sie auf Löschen.

Probleme mit veröffentlichten APIs beheben

Wenn bei „Ausprobieren“ der Fehler TypeError: Failed to fetch zurückgegeben wird, kann das folgende Ursachen haben:

  • Fehler aufgrund gemischter Inhalte werden möglicherweise durch ein bekanntes Problem mit der Swagger UI verursacht. Sie können das Problem möglicherweise umgehen, wenn Sie HTTPS in der Definition schemes Ihrer OpenAPI-Spezifikation vor HTTP angeben. Beispiel: 

     schemes:
   - https
   - http

  • Prüfen Sie bei Fehlern aufgrund von CORS-Einschränkungen (Cross-Origin Resource Sharing), ob Ihre API-Proxys CORS unterstützen. CORS ist ein Standardmechanismus, der clientseitige Cross-Origin-Anfragen ermöglicht. Weitere Informationen finden Sie unter Einem API-Proxy CORS-Unterstützung hinzufügen. CORS muss auch in Ihrem Browser aktiviert sein.