Informazioni sui modelli di percorso

In API Gateway è possibile indirizzare le richieste in entrata in base ai modelli di percorso. I modelli di percorso hanno tre componenti principali:

  • Corrispondenza esatta
  • Corrispondenza con caratteri jolly singola
  • Corrispondenza con due caratteri jolly

Le sezioni seguenti descrivono ciascuno di questi componenti e il loro funzionamento nel contesto di API Gateway.

Corrispondenza esatta

Un percorso basato su modello 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 potrebbe contenere una sezione come la seguente:

...
paths:
  /shelves:
    get:
      summary: List shelves
...

In questo esempio, il gateway accetterà solo richieste per /shelves e nessun altro percorso.

Corrispondenza con caratteri jolly singolo

Se un percorso basato su modelli contiene una variabile, un singolo segmento di caratteri jolly (ad esempio {var} o {var=*}) o entrambi, il gateway consentirà le richieste in entrata conformi a quanto segue:

  • Le richieste non contengono un'altra barra (/), il che significa che la variabile corrisponderà a un solo segmento di 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 potrebbe contenere una sezione come la 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 corrispondenti alla seguente regex:

^/shelves/[^/]+/books/[^/]+/?$

Corrispondenza con caratteri jolly doppio

Se un percorso basato su modello contiene una variabile indicata da un segmento di caratteri jolly doppi (ad es. {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 da 0 a 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 corrispondenti alla seguente regex:

^/shelves/[^/]+/books/.*/?$

Barra in avanti codificate nell'URL

API Gateway è conforme alla specifica RFC 3986, che non considera le barre (%2F) codificate nell'URL come barre effettive durante la corrispondenza dei percorsi degli URL per le decisioni di routing o di sicurezza. Se sono previsti slash codificati in URL, il tuo backend deve 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 è soggetta a restrizioni.

Nel caso in cui un utente invii una richiesta a /shelves/shelf_1%2Fbooks%2Fbook_2:

  • Il gateway elaborerà la richiesta come operazione GetShelf per l'ID sezione shelf_1%2Fbooks%2Fbook_2. In questo caso, il controllo delle chiavi API non viene applicato.
  • Se %2F viene normalizzato prima della gestione di qualsiasi richiesta 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 si aspetta che l'operazione GetBook esegua un controllo della chiave API nel gateway. Tuttavia, poiché il gateway ha letto la richiesta come operazione GetShelf, non è stato eseguito alcun controllo della chiave API.

Normalizzazione di più barre oblique adiacenti

API Gateway segue lo standard RFC 3986, che afferma che i percorsi con più barre oblique adiacenti verranno trattati in modo diverso rispetto a quelli con una sola barra obliqua. Ad esempio, una richiesta contenente /shelves/// non verrà normalizzata dal gateway al percorso della richiesta /shelves/ prima della corrispondenza a un modello di percorso URI né durante l'inoltro al backend specificato.