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.