Amazon API Gateway
Entwicklerhandbuch

TUTORIAL: Erstellen einer REST-API durch Importieren eines Beispiel

Sie können die Amazon API Gateway-Konsole zum Erstellen und Testen einer einfachen REST-API mit der HTTP-Integration für eine PetStore-Website verwenden. Die API-Definition ist als Swagger-2.0-Datei vorkonfiguriert. Nach dem Laden der API-Definition in API Gateway können Sie mit der API Gateway-Konsole die API-Grundstruktur erkunden oder die API einfach bereitstellen und testen.

Die PetStore-Beispiel-API unterstützt die folgenden Methoden für den Zugriff eines Clients auf die HTTP-Backend-Website von http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  • GET /: Für den Lesezugriff der Root-Ressource der API, die nicht mit jedem Backend-Endpunkt integriert ist. API Gateway antwortet mit einer Übersicht der PetStore-Website. Dies ist ein Beispiel für den MOCK-Integrationstyp.

  • GET /pets: Für den Lesezugriff auf die /pets-Ressource der API, die mit der gleichnamigen Backend-/pets-Ressource integriert ist. Das Backend gibt eine Seite mit den verfügbaren Haustieren in PetStore zurück. Dies ist ein Beispiel für den HTTP-Integrationstyp. Die URL des Integrationsendpunktes lautet http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  • POST /pets: Für den Schreibzugriff auf die /pets-Ressource der API, die mit der Backend-/petstore/pets-Ressource integriert ist. Nach dem Empfang einer korrekten Anforderung fügt das Backend das angegebene Haustier zum PetStore hinzu und gibt das Ergebnis an den Aufrufer zurück. Die Integration ist ebenfalls HTTP.

  • GET /pets/{petId}: Für den Lesezugriff auf ein Haustier, das durch einen petId-Wert per Pfadvariable der URL der eingehenden Anforderung identifiziert wird. Diese Methode hat ebenfalls den HTTP-Integrationstyp. Das Backend gibt das angegebene Haustier im PetStore zurück. Die URL des Backend-HTTP-Endpunkts ist http://petstore-demo-endpoint.execute-api.com/petstore/pets/n, wobei n eine Ganzzahl für die ID des abgefragten Haustiers ist.

Die API unterstützt den CORS-Zugriff über die OPTIONS-Methoden des MOCK-Integrationstyps. API Gateway gibt die für den CORS-Zugriff erforderlichen Header zurück.

Das folgende Verfahren führt Sie durch die Schritte zum Erstellen und Testen einer API anhand eines Beispiels unter Verwendung der API Gateway-Konsole.

So importieren, erstellen und testen Sie die Beispiel-API

  1. Sofern noch nicht geschehen, führen die Schritte unter Voraussetzungen: Vorbereiten auf das Erstellen einer API in API Gateway aus.

  2. Melden Sie sich unter https://console.aws.amazon.com/apigateway bei der API Gateway-Konsole an.

  3. Führen Sie eine der folgenden Aufgaben aus:

    1. Wenn dies die erste API in Ihrem Konto ist, wählen Sie auf der Willkommensseite der API Gateway-Konsole die Option Get Started aus.

      Wenn Sie dazu aufgefordert werden, klicken Sie auf OK, um sie zu schließen und fortzufahren.

    2. Wenn dies nicht Ihre erste API ist, wählen Sie Create API auf der API Gateway -APIs-Homepage aus:

  4. Wählen Sie unter Create new API Examples API und dann Import, um die Beispiel-API zu erstellen. Bei der ersten API beginnt die API Gateway-Konsole automatisch mit dieser Option.

    Sie können einen Bildlauf durch die OpenAPI-Definition ausführen und Details zu dieser Beispiel-API anzeigen. Klicken Sie anschließend auf Import.

  5. Die folgende Abbildung zeigt die neu erstellte API:

    Im Bereich Resources wird die Struktur der erstellten API als Knotenstruktur gezeigt. Die API-Methoden der einzelnen Ressourcen werden als Edges in der Struktur dargestellt. Bei Auswahl einer Ressource werden alle zugehörigen Methoden auf der rechten Seite im Bereich Methods angegeben. Unter der jeweiligen Methode befindet sich eine kurze Zusammenfassung der Methode mit Endpunkt-URL, Autorisierungstyp und Erforderlichkeit eines API-Schlüssels.

  6. Um die Details einer Methode anzuzeigen, die Einrichtung zu ändern oder den Methodenaufruf zu testen, wählen Sie entweder in der Methodenliste oder der Ressourcenstruktur einen Methodennamen aus. Zur Illustration wählen wir hier die Methode POST /pets:

    Der resultierende Bereich Method Execution zeigt eine logische Ansicht der Struktur der ausgewählten Methode (POST /pets) und ihrer Verhaltensweisen: Method Request und Method Response sind die Schnittstellen der API zu ihrem Frontend (einem Client), während Integration Request und Integration Response die Schnittstellen der API zu ihrem Backend (http://petstore-demo-endpoint.execute-api.com/petstore/pets) sind. Ein Client verwendet die API, um über die Methodenanforderung auf eine Backend-Funktion zuzugreifen. API Gateway übersetzt die Client-Anforderung, falls erforderlich, in das Formular, das für das Back-End in der Integrationsanforderung akzeptabel ist, bevor die eingehende Anforderung an das Back-End weitergeleitet wird. Die umgewandelte Anforderung wird als Integrationsanforderung bezeichnet. In ähnlicher Weise gibt das Back-End die Antwort an API Gateway in der Integrationsantwort zurück. API Gateway leitet es dann an Method Response weiter, bevor es an den Client gesendet wird. Falls erforderlich, kann API Gateway die Backend-Antwortdaten einem vom Client erwarteten Formular zuweisen.

    Für die POST-Methode einer API-Ressource kann die Nutzlast der Methodenanforderung ohne Änderung an die Integrationsanforderung übergeben werden, wenn die Nutzlast der Methodenanforderung dasselbe Format wie die Nutzlast der Integrationsanforderung aufweist.

    Die GET /-Methodenanforderung verwendet den Integrationstyp MOCK und ist nicht mit einem tatsächlichen Endpunkt im Backend verknüpft. Die entsprechende Integration Response ist so eingerichtet, dass sie eine statische HTML-Seite zurückgibt: Wenn die Methode aufgerufen wird, akzeptiert API Gateway einfach die Anforderung und gibt die konfigurierte Integrationsantwort sofort über Method Response an den Client zurück. Mit der Pseudo-Integration können Sie eine API testen, ohne dass ein Backend-Endpunkt erforderlich ist. Sie können sie auch zur Bereitstellung einer lokalen Antwort verwenden, die aufgrund einer Antwort-Textzuweisungsvorlage generiert wurde.

    Als API-Entwickler steuern Sie das Frontend-Interaktionsverhalten der API, indem Sie eine Methodenanforderung und eine Methodenantwort konfigurieren. Das Backend-Interaktionsverhalten der API steuern Sie, indem Sie eine Integrationsanforderung und eine Integrationsantwort einrichten. Dafür sind Datenzuweisungen zwischen einer Methode und der entsprechenden Integration nötig. Die Methodeneinrichtung wird im Thema TUTORIAL: Erstellen einer API mit benutzerdefinierter HTTP-Integration behandelt. Für den Moment konzentrieren wir uns darauf, die API zu testen, um eine umfassende Benutzererfahrung zu bieten.

  7. Wählen Sie Test auf Client (wie in der vorherigen Abbildung gezeigt) aus, um den Test zu starten. Geben Sie z. B. zum Testen der POST /pets-Methode die folgende {"type": "dog","price": 249.99}-Nutzlast in Request Body ein, bevor Sie die Schaltfläche Test betätigen.

    Die Eingabe gibt die Attribute für das Haustier (pet) an, das zur Liste der Haustiere auf der PetStore-Website hinzugefügt werden soll.

  8. Die Ergebnisse werden folgendermaßen angezeigt:

    In der Ausgabe werden unter Logs die Statusänderungen von der Methodenanforderung zur Integrationsanforderung und von der Integrationsantwort zur Methodenantwort angezeigt. Das ist hilfreich, um Zuweisungsfehler zu beheben, die zu einer fehlerhaften Anforderung führen. In diesem Beispiel wird keine Zuweisung angewendet: Die Nutzlast der Methodenanforderung wird über die Integrationsanforderung an das Backend übergeben und die Backend-Antwort wird parallel dazu über die Integrationsantwort an die Methodenantwort übergeben.

    Soll die API mit einem anderen Client als der "test-invoke-request"-Funktion von API Gateway getestet werden, muss die API zunächst für eine Stufe bereitgestellt werden.

  9. Um die Test-API bereitzustellen, wählen Sie die PetStore-API aus und wählen Sie dann Deploy API im Menü Aktionen.

    Wählen Sie in Deploy API für Deployment stage [New Stage], da dies die erste Bereitstellung der API ist. Geben Sie einen Namen (z. B. test) in Stage name ein, und geben Sie optional Beschreibungen in Stage description und Deployment description ein. Wählen Sie Deploy (Bereitstellen) aus.

    Im resultierenden Bereich Stage Editor zeigt Invoke URL die URL an, die die GET /-Methodenanfrage der API aufruft.

  10. Folgen Sie in Stage Editor dem Link Invoke URL, um die GET /-Methodenanfrage in einem Browser zu senden. Eine erfolgreiche Antwort gibt das Ergebnis zurück, das von der Zuweisungsvorlage in der Integrationsantwort generiert wurde.

  11. Erweitern Sie im Navigationsbereich Stages die Test-Stufe test, wählen Sie GET auf /pets/{petId} und kopieren Sie dann den Invoke URL-Wert von https://api-id.execute-api.region.amazonaws.com/test/pets/{petId}.{petId} steht für eine Pfadvariable.

    Fügen Sie den (im vorigen Schritt kopierten) Invoke URL-Wert in die Adresszeile des Browsers ein und ersetzen Sie {petId} durch z. B. 1. Drücken Sie zum Senden der Anforderung die Eingabetaste. Als Ergebnis wird die Antwort "200 OK" mit der folgenden JSON-Nutzlast zurückgegeben:

    { "id": 1, "type": "dog", "price": 249.99 }

    Die API-Methode kann auf diese Weise aufgerufen werden, da der Authorization-Typ auf NONE festgelegt ist. Falls die AWS_IAM-Autorisierung verwendet wird, muss die Anforderung mit Signature Version 4 (SigV4)-Protokollen signiert werden. Ein Beispiel für eine solche Anforderung finden Sie unter TUTORIAL: Erstellen einer API mit benutzerdefinierter HTTP-Integration.