Compreender a criação de modelos de caminhos

No gateway da API, é possível encaminhar pedidos recebidos com base na criação de modelos de caminhos. A criação de modelos de caminhos tem três componentes principais:

  • Correspondência exata
  • Correspondência de caráter universal único
  • Correspondência de caráter universal duplo

As secções seguintes descrevem cada um destes componentes e como funcionam no contexto do API Gateway.

Correspondência Exata

Um caminho baseado em modelos sem segmentos de carateres universais únicos ou duplos (* ou **) é convertido numa correspondência exata do caminho. Por exemplo, a especificação OpenAPI para a configuração da API de gateway pode conter uma secção semelhante à seguinte:

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

Neste exemplo, a entrada vai aceitar apenas pedidos para /shelves e nenhum outro caminho.

Correspondência de caráter universal único

Se um caminho baseado em modelos contiver uma variável, um segmento de caráter universal singular (por exemplo, {var} ou {var=*}) ou ambos, o gateway permite pedidos recebidos que estejam em conformidade com o seguinte:

  • Os pedidos não contêm uma barra invertida adicional (/), o que significa que a variável só corresponde a um único segmento de caminho.
  • Os pedidos contêm, pelo menos, um caráter.
  • Os pedidos podem conter uma barra invertida adicional no final do caminho, se estiver presente.

Por exemplo, a especificação OpenAPI para a configuração da API de gateway pode conter uma secção semelhante à seguinte:

...
paths:
  /shelves/{shelf}/books/{book}: # Equivalent to /shelves/{shelf=*}/books/{book=*}
    get:
      summary: Retrieve a book
...

Neste exemplo, o gateway aceita pedidos que correspondam à seguinte regex:

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

Correspondência de dois carateres universais

Se um caminho baseado em modelos contiver uma variável denotada por um segmento com dois carateres universais (por exemplo, {var=**}), o gateway permite pedidos recebidos que estejam em conformidade com o seguinte:

  • Os pedidos podem conter todos os carateres, incluindo barras (/).
  • Os pedidos podem conter 0 ou mais carateres.
  • Os pedidos podem conter uma barra invertida adicional no final do caminho, se estiver presente.

Por exemplo, a especificação OpenAPI para a configuração da API de gateway pode conter uma secção semelhante à seguinte:

...
paths:
  /shelves/{shelf=*}/books/{book=**}:
    get:
      summary: Retrieve a book
...

Neste exemplo, o gateway aceita pedidos que correspondam à seguinte regex:

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

Barras codificadas por URL

O API Gateway segue a RFC 3986, que não trata as barras invertidas com codificação de URL (%2F) como barras invertidas reais quando faz a correspondência de caminhos de URL para decisões de encaminhamento ou segurança. Se forem esperadas barras codificadas por URL, o seu back-end deve processar estes pedidos em conformidade.

Por exemplo, considere a seguinte especificação da 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: []

Neste exemplo, a operação /shelves/{shelf}/books/{book} requer uma chave da API, mas a operação /shelves/{shelf} não tem restrições.

No caso de um utilizador enviar uma solicitação para /shelves/shelf_1%2Fbooks%2Fbook_2:

  • O gateway processa o pedido como uma operação GetShelf para o ID da prateleira shelf_1%2Fbooks%2Fbook_2. Neste caso, a verificação da chave da API não é aplicada.
  • Se o %2F for normalizado antes do processamento de pedidos pelo back-end, o pedido pode, em alternativa, ser processado como a operação GetBook para o ID do livro book_2. Por outras palavras, os processos de back-end /shelves/shelf_1%2Fbooks%2Fbook_2 como /shelves/shelf_1/books/book_2.

Neste exemplo, o back-end espera que a operação GetBook faça uma verificação da chave da API no gateway. No entanto, uma vez que o gateway leu o pedido como uma operação GetShelf, não foi feita nenhuma verificação da chave da API.

Normalização de várias barras invertidas adjacentes

O API Gateway segue a RFC 3986, que afirma que os caminhos com várias barras invertidas adjacentes são tratados como um caminho diferente dos que têm barras invertidas singulares. Por exemplo, um pedido que contenha /shelves/// não é normalizado pela gateway para o caminho do pedido /shelves/ antes de corresponder a um modelo de caminho de URI nem ao encaminhar para o back-end especificado.