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 scaffale shelf_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 operazione GetBook per l'ID libro book_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.