Noções básicas sobre modelos de caminho

No gateway de API, é possível rotear solicitações recebidas com base na estimativa de caminho. As modelos de caminho têm três componentes principais:

• Correspondência exata
• Correspondência de caractere curinga único
• Correspondência de caractere curinga dupl

As seções a seguir descrevem cada um desses componentes e como eles funcionam no contexto do gateway de API.

Correspondência exata

Um caminho com modelo sem segmentos curinga únicos ou duplos (* ou **) é convertido em uma correspondência de caminho exata. Por exemplo, a especificação OpenAPI da configuração da API do gateway pode conter uma seção como esta

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

Neste exemplo, o gateway aceita apenas solicitações para /shelves e nenhum outro caminho.

Correspondência de caractere curinga único

Se um caminho com modelo tiver uma variável, um segmento de caractere curinga singular (por exemplo, {var} ou {var=*}) ou ambos, o gateway permitirá solicitações de entrada que estejam em conformidade com o seguinte:

• As solicitações não contêm uma barra (/), o que significa que a variável corresponderá apenas a um único segmento de caminho.
• As solicitações contêm pelo menos um caractere.
• As solicitações podem conter uma barra extra no final do caminho.

Por exemplo, a especificação OpenAPI da configuração da API do gateway pode conter uma seção como esta:

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

Neste exemplo, o gateway aceitará solicitações que correspondam ao seguinte regex:

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

Correspondência de caracteres curinga duplos

Se um caminho com modelo contiver uma variável indicada por um segmento de caractere curinga duplo (por exemplo, {var=**}), o gateway permitirá solicitações recebidas que estejam em conformidade com o seguinte:

• As solicitações podem conter todos caracteres, incluindo barras (/).
• As solicitações podem conter 0 ou mais caracteres.
• As solicitações podem conter uma barra extra no final do caminho.

Por exemplo, a especificação OpenAPI da configuração da API do gateway pode conter uma seção como esta:

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

Neste exemplo, o gateway aceitará solicitações que correspondam ao seguinte regex:

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

Barras de encaminhamento codificadas por URL

A API Gateway segue a RFC 3986 (em inglês), que não trata barras de barra de URL (%2F) como barras reais ao corresponder caminhos de URL para roteamento ou decisões de segurança. Se forem esperadas barras codificadas de URL, o back-end deverá processar essas solicitações adequadamente.

Por exemplo, considere a seguinte especificação 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 de API, mas a operação /shelves/{shelf} não é restrita.

Se um usuário enviar uma solicitação para /shelves/shelf_1%2Fbooks%2Fbook_2:

• O gateway processará a solicitação como uma operação GetShelf para o ID da estante shelf_1%2Fbooks%2Fbook_2. Nesse caso, uma verificação de chave de API não é obrigatória.
• Se o %2F for normalizado antes de qualquer solicitação ser processada pelo back-end, a solicitação poderá ser processada como a operação GetBook do ID do livro book_2. Em outras palavras, o back-end processa /shelves/shelf_1%2Fbooks%2Fbook_2 como /shelves/shelf_1/books/book_2.

Neste exemplo, o back-end espera que a operação GetBook execute uma verificação de chave de API no gateway. No entanto, como o gateway leu a solicitação como uma operação GetShelf, nenhuma verificação de chave de API foi realizada.

Normalização de vários retângulos adjacentes

A API Gateway segue a RFC 3986 (em inglês), que declara que os caminhos com várias barras adjacentes serão tratados como caminhos diferentes daqueles com barras no singular. Por exemplo, uma solicitação que contém /shelves/// não será normalizada pelo gateway para o caminho da solicitação /shelves/ antes de corresponder a um modelo de caminho de URI nem ao encaminhar para o back-end especificado.