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 estanteshelf_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çãoGetBook
do ID do livrobook_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.