Información sobre las plantillas de ruta

En API Gateway, es posible enrutar las solicitudes entrantes según las plantillas de rutas. Las plantillas de rutas de acceso 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 de comodín único 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 tu 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 a ninguna otra ruta.

Nota: Las barras diagonales codificadas en URL (%2F) no se tratarán como barras diagonales reales, lo que significa que %2Fshelves no coincidirá con la operación de OpenAPI que se describió anteriormente en la especificación.

Coincidencia de comodín único

Si una ruta de acceso con plantilla contiene una variable, un segmento de comodín único ({var}) o, solo en OpenAPI 2.0, un segmento de comodín único ({var=*}), la puerta de enlace permitirá las solicitudes entrantes que cumplan con lo siguiente:

• Las solicitudes no contienen una barra adicional (/), lo que significa que la variable solo coincidirá con un segmento de ruta de acceso.
• Las solicitudes contienen al menos un carácter.
• Las solicitudes pueden contener una barra final adicional si está presente al final de la ruta.

Nota: Para la expansión de variables, todos los caracteres, excepto [-_.~/0-9a-zA-Z], se codifican como porcentaje.

Por ejemplo, la especificación de OpenAPI para la configuración de la API de tu 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 expresión regular:

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

Nota: Si usas una especificación de OpenAPI 3.x, no se admite la sintaxis /shelves/{shelf=*}/books/{book=*} y se rechazará.

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á presente al final de la ruta.

Nota: Si usas una especificación de OpenAPI 3.x, no se admite la sintaxis de comodín doble. En el caso de las especificaciones de OpenAPI 2.0, las variables de comodín doble solo se pueden usar en el último segmento de la ruta proporcionada. Esto significa que /shelves/{shelf=**}/books/{book=**} no está permitido, ya que {shelf=**} no se declara en el último segmento de la ruta. Para la expansión de variables, todos los caracteres, excepto [-_.~/0-9a-zA-Z], se codifican como porcentaje.

Por ejemplo, la especificación de OpenAPI para la configuración de la API de tu puerta de enlace puede contener una sección como la siguiente:

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: '**'
...

En este ejemplo, la puerta de enlace aceptará solicitudes en las que el parámetro book coincida con cualquier carácter, incluidas las barras diagonales. Esto corresponde a la siguiente expresión regular:

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

Barras diagonales codificadas para URL

API Gateway sigue la RFC 3986, que no trata las barras diagonales codificadas en URL (%2F) como barras reales cuando se comparan las rutas de acceso de URL para tomar decisiones de enrutamiento o seguridad. Si se esperan barras diagonales codificadas en URL, tu backend debe controlar estas solicitudes de manera adecuada.

Advertencia: Si tu backend espera que las barras diagonales codificadas en URL (%2F) se traten como barras reales cuando se coinciden con las plantillas de ruta de acceso de API Gateway, las solicitudes que contienen barras diagonales de URL codificadas pueden coincidir con operaciones inesperadas y generan un acceso con privilegios excesivos a los recursos de backend.

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, ocurrirá lo siguiente:

• La puerta de enlace procesará la solicitud como una operación GetShelf para el ID de la biblioteca shelf_1%2Fbooks%2Fbook_2. En este caso, no se aplica la verificación de la clave de API.
• Si el backend normaliza el %2F antes de procesar cualquier solicitud, es posible que la solicitud se procese como la operación GetBook para el ID de libro book_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 la 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 la clave de API.

Normalización de varias 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 ni cuando se reenvía al backend especificado.

Advertencia: Si tu backend normaliza las rutas de acceso de URL combinando varias barras diagonales en una sola, las solicitudes que contengan varias barras diagonales adyacentes pueden coincidir con operaciones inesperadas de la puerta de enlace y generar un acceso con privilegios excesivos a tus recursos de backend.