Tutorial: Erstellen einer REST-API durch Importieren eines Beispiels - Amazon API Gateway

Tutorial: Erstellen einer REST-API durch Importieren eines Beispiels

Sie können die Amazon API Gateway-Konsole verwenden, um eine einfache REST-API mit der HTTP-Integration für eine PetStore-Website zu erstellen und zu testen. Die API-Definition ist als Swagger-2.0-Datei vorkonfiguriert. Nachdem Sie die API-Definition in API Gateway geladen haben, können Sie die API Gateway-Konsole verwenden, um die Grundstruktur der API zu untersuchen 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 reagiert mit einem Überblick über die 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 erforderlichen Header zurück, die den CORS-Zugriff unterstützen.

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

So importieren, erstellen und testen Sie die Beispiel-API

  1. Sofern noch nicht geschehen, führen die Schritte unter au Voraussetzungen für die ersten Schritte mit API Gateway.

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

  3. Wenn Sie API Gateway zum ersten Mal verwenden, sehen Sie eine Seite, die Sie mit den Funktionen des Service vertraut macht. Wählen Sie unter REST-API die Option Build (Erstellen) aus. Wenn das Popup-Fenster Create Exampe API (Beispiel-API erstellen) angezeigt wird, klicken Sie auf OK.

    Wenn Sie API Gateway nicht zum ersten Mal verwenden, wählen Sie Create API (API erstellen). Wählen Sie unter REST-API die Option Build (Erstellen) aus.

  4. Wählen Sie unter Create new API Examples API und dann Import, um die Beispiel-API zu erstellen. Für Ihre erste API startet die API Gateway-Konsole mit dieser Option als Standard.

    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 für den Zugriff auf eine Backend-Funktion über Method Request. Bei Bedarf wandelt Amazon API Gateway die Clientanforderung in ein Format um, das vom Backend in Integration Request (Integrationsanfrage) verarbeitet werden kann, bevor die eingehende Anfrage an das Backend weitergeleitet wird. Die umgewandelte Anforderung wird als Integrationsanforderung bezeichnet. Analog dazu gibt das Backend die Antwort an API Gateway in Integration Response (Integrationsantwort) zurück. API Gateway leitet dann an Method Response (Methodenantwort) weiter, bevor das Senden an den Client erfolgt. Auch hier kann API Gateway, falls erforderlich, die Backend-Antwortdaten einer vom Client erwarteten Form zuordnen.

    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 Anfrage 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-TextMapping-Vorlage 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 behandel Tutorial: REST-API mit HTTP-API ohne Proxy-Integration erstellen. 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.

    Um die API mit einem Client zu testen, der nicht die test-invoke-request-Funktion von API Gateway verwendet, müssen Sie die API zunächst auf einer Stufe bereitstellen.

  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 Mapping-Vorlage in der Integrationsantwort generiert wurde.

  11. Erweitern Sie im Navigationsbereich Stufen die Stufe Test, wählen Sie GET für /pets/{petId} aus und kopieren Sie dann den Aufruf-URL-Wert 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 Anfrage mit Signature Version 4 (SigV4)-Protokollen signiert werden. Ein Beispiel für eine solche Anforderung finden Sie unter Tutorial: REST-API mit HTTP-API ohne Proxy-Integration erstellen.