Informazioni sui modelli di percorso
All'interno di API Gateway, è possibile instradare le richieste in entrata in base ai modelli di percorso. I modelli dei percorsi hanno tre componenti principali:
- Corrispondenza esatta
- Corrispondenza con carattere jolly singolo
- Corrispondenza carattere jolly doppio
Le seguenti sezioni descrivono ciascuno di questi componenti e il loro funzionamento nel contesto di API Gateway.
Corrispondenza esatta
Un percorso basato su modelli senza segmenti con caratteri jolly singoli o doppi (*
o **
) viene convertito in una corrispondenza esatta del percorso.
Ad esempio, la specifica OpenAPI per la configurazione dell'API gateway può contenere una sezione simile alla seguente:
...
paths:
/shelves:
get:
summary: List shelves
...
In questo esempio, il gateway accetterà solo richieste a /shelves
e nessun altro percorso.
Corrispondenza con carattere jolly singolo
Se un percorso basato su modelli contiene una variabile, un singolo segmento con caratteri jolly (ad es.{var}
o {var=*}
) o entrambi, il gateway consentirà le richieste in entrata conformi a quanto segue:
- Le richieste non contengono una barra (
/
), pertanto la variabile corrisponderà a un solo segmento del percorso. - Le richieste contengono almeno un carattere.
- Le richieste possono contenere una barra finale aggiuntiva, se presente alla fine del percorso.
Ad esempio, la specifica OpenAPI per la configurazione dell'API gateway può contenere una sezione simile alla seguente:
...
paths:
/shelves/{shelf}/books/{book}: # Equivalent to /shelves/{shelf=*}/books/{book=*}
get:
summary: Retrieve a book
...
In questo esempio, il gateway accetterà le richieste che corrispondono alla seguente regex:
^/shelves/[^/]+/books/[^/]+/?$
Corrispondenza con doppio carattere jolly
Se un percorso basato su modelli contiene una variabile indicata da un doppio segmento con caratteri jolly (ad esempio {var=**}
), il gateway consentirà le richieste in entrata conformi a quanto segue:
- Le richieste possono contenere tutti i caratteri, incluse le barre (/).
- Le richieste possono contenere 0 o più caratteri.
- Le richieste possono contenere una barra finale aggiuntiva, se presente alla fine del percorso.
Ad esempio, la specifica OpenAPI per la configurazione dell'API gateway può contenere una sezione simile alla seguente:
...
paths:
/shelves/{shelf=*}/books/{book=**}:
get:
summary: Retrieve a book
...
In questo esempio, il gateway accetterà le richieste che corrispondono alla seguente regex:
^/shelves/[^/]+/books/.*/?$
Barra di inoltro codificata nell'URL
API Gateway è conforme alla specifica RFC 3986, che non considera le barre codificate negli URL (%2F
) come barre effettive durante la corrispondenza dei percorsi degli URL per le decisioni di routing o di sicurezza. Se sono previste barre codificate nell'URL, il backend dovrebbe gestire queste richieste di conseguenza.
Ad esempio, considera la seguente specifica OpenAPI:
securityDefinitions:
api_key:
type: "apiKey"
name: "key"
in: "query"
paths:
/shelves/{shelf}:
get:
parameters:
- in: path
name: shelf
type: string
required: true
description: Shelf ID.
summary: List shelves
operationId: GetShelf
responses:
'200':
description: A successful response
schema:
type: string
/shelves/{shelf}/books/{book}:
get:
parameters:
- in: path
name: shelf
type: string
required: true
description: Shelf ID.
- in: path
name: book
type: string
required: true
description: Book ID
summary: Retrieve a book
operationId: GetBook
responses:
'200':
description: A successful response
schema:
type: string
security:
- api_key: []
In questo esempio, l'operazione /shelves/{shelf}/books/{book}
richiede una chiave API, ma l'operazione /shelves/{shelf}
non prevede restrizioni.
Nel caso in cui un utente invii una richiesta a /shelves/shelf_1%2Fbooks%2Fbook_2
:
- Il gateway elaborerà la richiesta come un'operazione
GetShelf
per l'ID scaffaleshelf_1%2Fbooks%2Fbook_2
. In questo caso, non viene applicato in modo forzato un controllo della chiave API. - Se
%2F
viene normalizzato prima di qualsiasi gestione delle richieste da parte del backend, la richiesta potrebbe essere elaborata come operazioneGetBook
per l'ID librobook_2
. In altre parole, il backend elabora/shelves/shelf_1%2Fbooks%2Fbook_2
come/shelves/shelf_1/books/book_2
.
In questo esempio, il backend prevede che l'operazione GetBook
esegua un controllo della chiave API a livello di gateway. Tuttavia, poiché il gateway ha letto la richiesta come un'operazione GetShelf
, non è stato eseguito alcun controllo della chiave API.
Normalizzazione di più barre in avanti adiacenti
Il gateway API segue la specifica RFC 3986, che stabilisce che i percorsi con più barre adiacenti verranno trattati come un percorso diverso rispetto a quelli con barre singolari.
Ad esempio, una richiesta contenente /shelves///
non verrà normalizzata dal gateway nel percorso della richiesta /shelves/
prima di trovare corrispondenze di un modello di percorso URI nor al momento dell'inoltro al backend specificato.