Comprende el uso de plantillas de ruta
Dentro de API Gateway, es posible enrutar las solicitudes entrantes según las plantillas de ruta de acceso. Las plantillas de ruta tienen tres componentes principales:
- Coincidencia exacta
- Coincidencia de comodines únicos
- Coincidencia de comodines dobles
En las siguientes secciones, se describe cada uno de estos componentes y cómo funcionan dentro del contexto de API Gateway.
Coincidencia exacta
Una ruta de acceso con plantilla sin ningún segmento comodín simple o doble (*
o **
) se convierte en una coincidencia de ruta de acceso exacta.
Por ejemplo, la especificación de OpenAPI para la configuración de la API de puerta de enlace puede contener una sección como la siguiente:
...
paths:
/shelves:
get:
summary: List shelves
...
En este ejemplo, la puerta de enlace solo aceptará solicitudes a /shelves
y ninguna otra ruta de acceso.
Coincidencia con un solo comodín
Si una ruta de acceso con plantilla contiene una variable, un segmento de comodín único (p. ej., {var}
o {var=*}
), o ambos, la puerta de enlace permitirá las solicitudes entrantes que cumplan con lo siguiente:
- Las solicitudes no contienen una barra diagonal adicional (
/
), lo que significa que la variable solo coincidirá con un segmento de ruta único. - Las solicitudes contienen al menos un carácter.
- Las solicitudes pueden contener una barra final adicional si están presentes al final de la ruta de acceso.
Por ejemplo, la especificación de OpenAPI para la configuración de la API de puerta de enlace puede contener una sección como la siguiente:
...
paths:
/shelves/{shelf}/books/{book}: # Equivalent to /shelves/{shelf=*}/books/{book=*}
get:
summary: Retrieve a book
...
En este ejemplo, la puerta de enlace aceptará solicitudes que coincidan con la siguiente regex:
^/shelves/[^/]+/books/[^/]+/?$
Coincidencia de comodines dobles
Si una ruta de acceso con plantilla contiene una variable denotada por un segmento de comodín doble (p. ej. {var=**}
), la puerta de enlace permitirá las solicitudes entrantes que cumplan con lo siguiente:
- Las solicitudes pueden contener todos los caracteres, incluidas las barras diagonales (/).
- Las solicitudes pueden contener 0 o más caracteres.
- Las solicitudes pueden contener una barra final adicional si están presentes al final de la ruta de acceso.
Por ejemplo, la especificación de OpenAPI para la configuración de la API de puerta de enlace puede contener una sección como la siguiente:
...
paths:
/shelves/{shelf=*}/books/{book=**}:
get:
summary: Retrieve a book
...
En este ejemplo, la puerta de enlace aceptará solicitudes que coincidan con la siguiente regex:
^/shelves/[^/]+/books/.*/?$
Barras directas codificadas para URL
API Gateway sigue a RFC 3986, que no trata las barras diagonales codificadas en la URL (%2F
) como barras reales cuando hacen coincidir las rutas de URL para el enrutamiento o las decisiones de seguridad. Si se esperan barras con codificación URL, tu backend debería manejar estas solicitudes según corresponda.
Por ejemplo, considera la siguiente especificación de 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: []
En este ejemplo, la operación /shelves/{shelf}/books/{book}
requiere una clave de API, pero la operación /shelves/{shelf}
no está restringida.
En el caso de que un usuario envíe una solicitud a /shelves/shelf_1%2Fbooks%2Fbook_2
, haz lo siguiente:
- La puerta de enlace procesará la solicitud como una operación
GetShelf
para el ID de bibliotecashelf_1%2Fbooks%2Fbook_2
. En este caso, no se aplica de manera forzosa una verificación de clave de API. - Si
%2F
se normaliza antes de que el backend maneje cualquier solicitud, la solicitud se puede procesar como la operaciónGetBook
para el ID del librobook_2
. En otras palabras, el backend procesa/shelves/shelf_1%2Fbooks%2Fbook_2
como/shelves/shelf_1/books/book_2
.
En este ejemplo, el backend espera que la operación GetBook
realice una verificación de clave de API en la puerta de enlace. Sin embargo, debido a que la puerta de enlace leyó la solicitud como una operación GetShelf
, no se realizó ninguna verificación de clave de API.
Normalización de múltiples barras diagonales adyacentes
API Gateway sigue la RFC 3986, que indica que las rutas con varias barras diagonales adyacentes se tratarán como una ruta de acceso diferente de las que tienen barras diagonales únicas.
Por ejemplo, una solicitud que contiene /shelves///
no será normalizada por la puerta de enlace a la ruta de la solicitud /shelves/
antes de hacer coincidir una plantilla de ruta del URI nor cuando se reenvía al el backend especificado.