Sviluppo di REST API in Gateway API - Amazon API Gateway

Sviluppo di REST API in Gateway API

In Amazon API Gateway è possibile creare un'API REST come una raccolta di entità programmabili note come risorse di API Gateway. Ad esempio, puoi usare una risorsa RestApi per rappresentare un'API che può contenere una raccolta di entità Resource.

Ciascuna entità Resource può presentare una o più risorse Method. Method è una richiesta in entrata inviata dal client che può contenere un parametro di percorso, un’intestazione o un parametro della stringa di query. Inoltre, a seconda del metodo HTTP, la richiesta può contenere un corpo. Il metodo definisce in che modo il client accede alla Resource esposta. Per integrare Method con un endpoint di backend, noto anche come endpoint di integrazione, devi creare una risorsa Integrazione. In questo modo la richiesta in arrivo viene inoltrata all'URI dell'endpoint di integrazione specificato. Se necessario, è possibile trasformare i parametri o il corpo della richiesta per soddisfare i requisiti del backend oppure creare un’integrazione proxy, in cui Gateway API invia l’intera richiesta in un formato standardizzato all’URI dell’endpoint di integrazione e quindi invia la risposta direttamente al client.

Per le risposte, è possibile creare una risorsa MethodResponse per rappresentare una risposta ricevuta dal client e una risorsa IntegrationResponse per rappresentare la risposta restituita dal backend. Si utilizza la risposta di integrazione per trasformare i dati della risposta del backend prima di restituirli al client oppure si passa la risposta del backend al client senza modificarla.

Risorsa di esempio per una REST API

Il diagramma seguente mostra come Gateway API implementa il modello di richiesta/risposta per un proxy HTTP e un’integrazione HTTP non proxy per la risorsa GET /pets. Il client invia l’intestazione x-version:beta a Gateway API che quindi invia il codice di stato 204 al client.

Nell’integrazione non proxy, Gateway API esegue le trasformazioni di dati per soddisfare i requisiti del backend, modificando la richiesta e la risposta di integrazione. In un’integrazione non proxy, è possibile accedere al corpo nella richiesta di metodo ma è necessario trasformarlo nella richiesta di integrazione. Quando l’endpoint di integrazione restituisce una risposta con un corpo, è necessario accedere e trasformarlo nella risposta di integrazione. Non è possibile modificare il corpo nella risposta di metodo.

Nell’integrazione proxy, l’endpoint di integrazione modifica la richiesta e la risposta. Gateway API non modifica la richiesta o la risposta di integrazione e invia la richiesta in entrata al backend così com’è.

Indipendentemente dal tipo di integrazione, il client ha inviato una richiesta a Gateway API che ha risposto in modo sincrono.

Non-proxy integration
Diagramma dell’integrazione non proxy di Gateway API
Proxy integration
Diagramma dell’integrazione proxy di Gateway API

I log di esecuzione seguenti mostrano cosa dell’esempio precedente Gateway API registra nei log. Per maggiore chiarezza, alcuni valori e log iniziali sono stati rimossi:

Non-proxy integration
Wed Feb 12 23:56:44 UTC 2025 : Starting execution for request: abcd-1234-5678 Wed Feb 12 23:56:44 UTC 2025 : HTTP Method: GET, Resource Path: /pets Wed Feb 12 23:56:44 UTC 2025 : Method request path: {} Wed Feb 12 23:56:44 UTC 2025 : Method request query string: {} Wed Feb 12 23:56:44 UTC 2025 : Method request headers: {x-version=beta} Wed Feb 12 23:56:44 UTC 2025 : Method request body before transformations: Wed Feb 12 23:56:44 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:56:44 UTC 2025 : Endpoint request headers: {app-version=beta} Wed Feb 12 23:56:44 UTC 2025 : Endpoint request body after transformations: Wed Feb 12 23:56:44 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:56:45 UTC 2025 : Received response. Status: 200, Integration latency: 123 ms Wed Feb 12 23:56:45 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:56:45 GMT} Wed Feb 12 23:56:45 UTC 2025 : Endpoint response body before transformations: Wed Feb 12 23:56:45 UTC 2025 : Method response body after transformations: (null) Wed Feb 12 23:56:45 UTC 2025 : Method response headers: {X-Amzn-Trace-Id=Root=1-abcd-12345} Wed Feb 12 23:56:45 UTC 2025 : Successfully completed execution Wed Feb 12 23:56:45 UTC 2025 : Method completed with status: 204
Proxy integration
Wed Feb 12 23:59:42 UTC 2025 : Starting execution for request: abcd-1234-5678 Wed Feb 12 23:59:42 UTC 2025 : HTTP Method: GET, Resource Path: /pets Wed Feb 12 23:59:42 UTC 2025 : Method request path: {} Wed Feb 12 23:59:42 UTC 2025 : Method request query string: {} Wed Feb 12 23:59:42 UTC 2025 : Method request headers: {x-version=beta} Wed Feb 12 23:59:42 UTC 2025 : Method request body before transformations: Wed Feb 12 23:59:42 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:59:42 UTC 2025 : Endpoint request headers: { x-version=beta} Wed Feb 12 23:59:42 UTC 2025 : Endpoint request body after transformations: Wed Feb 12 23:59:42 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:59:43 UTC 2025 : Received response. Status: 204, Integration latency: 123 ms Wed Feb 12 23:59:43 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT} Wed Feb 12 23:59:43 UTC 2025 : Endpoint response body before transformations: Wed Feb 12 23:59:43 UTC 2025 : Method response body after transformations: Wed Feb 12 23:59:43 UTC 2025 : Method response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT} Wed Feb 12 23:59:43 UTC 2025 : Successfully completed execution Wed Feb 12 23:59:43 UTC 2025 : Method completed with status: 204

Per importare un’API simile e testarla nella AWS Management Console, consultare l’API di esempio.

Funzionalità aggiuntive per lo sviluppo di REST API

Gateway API supporta funzionalità aggiuntive per lo sviluppo della REST API. Ad esempio, per aiutare i clienti a comprendere l’API, è possibile fornire la documentazione relativa all’API. A questo scopo, aggiungi una risorsa DocumentationPart per un'entità API supportata.

Per controllare il modo in cui i client chiamano un'API, usa le autorizzazioni IAM, un'autorizzazione Lambda o un pool di utenti di Amazon Cognito. Per misurare l'uso dell'API, configura piani di utilizzo per eseguire il throttling delle richieste API. Puoi abilitare queste impostazioni durante la creazione o l'aggiornamento dell'API.

Il diagramma seguente mostra le funzionalità disponibili per lo sviluppo di REST API e dove tali funzionalità sono configurate nel modello di richiesta/risposta.

Diagramma delle funzionalità di Gateway API

Per un'introduzione su come creare un'API, consulta Tutorial: creazione di una REST API con un'integrazione proxy Lambda. Per ulteriori informazioni sulle funzionalità di Gateway API che potresti utilizzare durante lo sviluppo di una REST API, consulta i seguenti argomenti. Questi argomenti contengono informazioni concettuali e procedure che puoi eseguire utilizzando la console Gateway API, la REST API di Gateway API, l'interfaccia AWS CLI o uno degli SDK AWS.