Noções básicas sobre modelos de caminho

No gateway de API, é possível rotear solicitações recebidas com base no modelo de caminho. Um modelo de caminho tem 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.

Observação: as barras codificadas pelo URL (%2F) não serão tratadas como barras reais, o que significa que %2Fshelves não será correspondente. a operação OpenAPI descrita anteriormente na especificação.

Correspondência de caractere curinga único

Se um caminho com modelo tiver uma variável, um segmento de caractere curinga singular ({var}) ou, somente no OpenAPI 2.0, um segmento de caractere curinga singular ({var=*}), 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.

Observação: para expansão variável, todos os caracteres, exceto [-_.~/0-9a-zA-Z], são codificados por porcentagem.

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 à seguinte expressão regular:

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

Observação: se você estiver usando uma especificação OpenAPI 3.x, a sintaxe /shelves/{shelf=*}/books/{book=*} não é compatível e será rejeitada.

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.

Observação: se você estiver usando uma especificação OpenAPI 3.x, a sintaxe de caractere curinga duplo não será aceita. Para especificações OpenAPI 2.0, as variáveis de caractere curinga duplo só podem ser usadas no último segmento do caminho fornecido. Isso significa que o /shelves/{shelf=**}/books/{book=**} não é permitido porque {shelf=**} não está declarado no último segmento do caminho. Para a expansão variável, todos os caracteres, exceto [-_.~/0-9a-zA-Z], são codificados por porcentagem.

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

OpenAPI 2.0

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

OpenAPI 3.x

...
paths:
  /shelves/{shelf}/books/{book}:
    get:
      summary: Retrieve a book
      parameters:
      - name: shelf
        in: path
        schema:
          type: string
      - name: book
        in: path
        schema:
          type: string
        x-google-parameter:
          pattern: '**'
...

Neste exemplo, o gateway aceitará solicitações em que o parâmetro book corresponda a qualquer caractere, incluindo barras. Isso corresponde à seguinte expressão regular:

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

Barras codificadas por URL

O gateway de API segue RFC 3986, que não trata barras de URL codificadas (%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.

Aviso: se seu back-end esperar que as barras de encaminhamento de URL codificadas (%2F) sejam tratadas como barras reais ao corresponder aos modelos de caminho do gateway de API, as solicitações que tiverem barras de URL codificadas poderão corresponder a inesperadas operações e resultam em acesso muito privilegiado aos recursos de back-end.

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

O gateway de API segue RFC 3986, 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.

Aviso: se o back-end normalizar os caminhos de URL mesclando várias barras para uma única barra, as solicitações que tiverem várias barras adjacentes poderão corresponder a operações inesperadas de gateway e resultar em excesso de privilégios. acesso aos recursos de back-end.

Regras de sintaxe

O gateway de API aplica várias regras de validação de sintaxe para modelos de caminho:

• Convenções de nomenclatura de variáveis:os nomes de variáveis precisam começar com uma letra (minúscula ou maiúscula) ou um sublinhado (_) e só podem conter letras, números, sublinhados, pontos (.) e hifens (-).
  • Válido: {my_var}, {var-1}, {var.name}
  • Inválido: {1var}, {my var}
• Sem mistura de parâmetros e literais:um único segmento de caminho não pode conter um parâmetro e caracteres literais.
  • Válido: /prefix/{var}
  • Inválido: /prefix-{var}, /{var}suffix
• Sufixo de método personalizado permitido:a única exceção à mistura de parâmetros e literais está no último segmento do caminho, em que um sufixo de método personalizado que começa com dois pontos (:) é permitido.
  • Válido: /{var}:customMethod
  • Inválido: /{var}:customMethod/suffix
• Sem vários parâmetros por segmento:um único segmento de caminho não pode conter mais de um parâmetro.
  • Válido: /{var1}/{var2}
  • Inválido: /{var1}{var2}
• Sem parâmetros aninhados:os parâmetros não podem ser aninhados uns nos outros.
  • Válido: /{var}
  • Inválido: /{{var}}
• Caractere curinga duplo: os segmentos de caractere curinga duplo só podem estar no último segmento do caminho.
  • Válido: /prefix/{var=**}, /prefix/**
  • Inválido: /{var=**}/suffix, /**/suffix

Limites

Limite	Valor
Número de parâmetros por caminho	60
Comprimento do nome da variável	100
Tamanho do caminho (com ou sem modelo)	512