Tutorial: Erstellen einer REST-API durch Importieren eines Beispiels

Sie können die Amazon API Gateway 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, mit denen ein Client auf die HTTP-Backend-Website von http://petstore-demo-endpoint.execute-api.com/petstore/pets zugreifen kann.

Anmerkung

In diesem Tutorial wird ein HTTP-Endpunkt als Beispiel verwendet. Wenn Sie Ihre eigenen APIs erstellen, empfehlen wir Ihnen, HTTPS-Endpunkte für Ihre HTTP-Integrationen zu verwenden.

• GET /: Für den Lesezugriff der Root-Ressource der API, die nicht mit jedem Backend-Endpunkt integriert ist. API Gateway antwortet 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 verfügbaren Haustieren in der 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 Erhalt einer korrekten Anfrage fügt das Backend das angegebene Haustier zur Liste hinzu PetStore und gibt das Ergebnis an den Anrufer 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 zurück, das in der gefunden wurde. PetStore 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. Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

2. Führen Sie eine der folgenden Aktionen aus:

   • Um Ihre erste API zu erstellen, wählen Sie für REST-API die Option Erstellen.

   • Wenn Sie zuvor eine API erstellt haben, wählen Sie API erstellen und dann für REST-API die Option Erstellen.

3. Wählen Sie unter Create REST API (REST API erstellen) die Option Example API (Beispiel-API) und dann Create API (API erstellen) aus, um die Beispiel-API zu erstellen.

   

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

4. Klicken Sie im Hauptnavigationsbereich auf Resources (Ressourcen). 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 in der Tabelle Methods (Methoden) angegeben. Bei jeder Methode werden der Methodentyp, der Integrationstyp, der Autorisierungstyp und die API-Schlüsselanforderung angezeigt.

5. 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 daraufhin angezeigte Bereich zur Methodenausführung bietet eine logische Ansicht der Struktur und des Verhaltens der ausgewählten (POST /pets) Methode.

   Die Method request (Methodenanforderung) und die Method response (Methodenantwort) stellen die Schnittstelle der API zum Frontend dar, und die Integration request (Integrationsanforderung) und die Integration response (Integrationsantwort) stellen die Schnittstelle der API zum Backend dar.

   Ein Client verwendet die API für den Zugriff auf eine Backend-Funktion über Method Request (Methodenanforderung). 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 (Integrationsantwort) 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 (Methodenantwort) 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. Im Moment konzentrieren wir uns darauf, die API zu testen, um eine end-to-end Benutzererfahrung zu bieten.

6. Wählen Sie die Registerkarte Test. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte anzuzeigen.

7. Geben Sie z. B. zum Testen der POST /pets-Methode die folgende {"type": "dog","price": 249.99}-Nutzlast in Request Body (Anforderungstext) ein, bevor Sie die Schaltfläche Test betätigen.

   

   Die Eingabe gibt die Attribute des Haustiers an, das wir der Liste der Haustiere auf der PetStore Website hinzufügen möchten.

8. Die Ergebnisse werden folgendermaßen angezeigt:

   

   In der Ausgabe werden unter Log (Protokoll) 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 anderen Client als der API Gateway test-invoke-request Gateway-Funktion zu testen, müssen Sie die API zunächst in einer Phase bereitstellen.

9. Wählen Sie Deploy API (API bereitstellen) aus, um die Beispiel-API bereitzustellen.

   

10. Wählen Sie für Stage (Stufe) die Option New stage (Neue Stufe) aus, und geben Sie dann test ein.

11. (Optional) Geben Sie unter Description (Beschreibung) eine Beschreibung ein.

12. Wählen Sie Bereitstellen.

13. Im resultierenden Bereich Stages (Stufen) zeigt Invoke URL (Aufruf-URL) unter Stage details (Stufendetails) die URL an, die die GET /-Methodenanfrage der API aufruft.

    

14. Wählen Sie das Kopiersymbol, um die Aufruf-URL Ihrer API zu kopieren, und geben Sie dann die Aufruf-URL Ihrer API in einen Webbrowser ein. Eine erfolgreiche Antwort gibt das Ergebnis zurück, das von der Mapping-Vorlage in der Integrationsantwort generiert wurde.

15. 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.