Información sobre la creación de plantillas de ruta

En API Gateway, es posible enrutar las solicitudes entrantes en función de las plantillas de ruta. Las plantillas de ruta tienen tres componentes principales:

• Concordancia exacta
• Coincidencia con un solo comodín
• Coincidencia con doble comodín

En las siguientes secciones se describe cada uno de estos componentes y cómo funcionan en el contexto de API Gateway.

Concordancia exacta

Una ruta con plantilla sin ningún segmento de comodín simple o doble (* o **) se convierte en una coincidencia de ruta exacta. Por ejemplo, la especificación de OpenAPI de la configuración de la API de tu pasarela puede contener una sección como la siguiente:

...
paths:
  /shelves:
    get:
      summary: List shelves
...

En este ejemplo, la pasarela solo aceptará solicitudes a /shelves y a ninguna otra ruta.

Nota: Las barras inclinadas con codificación URL (%2F) no se tratarán como barras inclinadas reales, lo que significa que %2Fshelves no coincidirá con la operación de OpenAPI anterior.

Coincidencia con un solo comodín

Si una ruta con plantilla contiene una variable, un segmento comodín singular (por ejemplo, {var} o {var=*}) o ambos, la pasarela permitirá las solicitudes entrantes que cumplan lo siguiente:

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

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

Por ejemplo, la especificación de OpenAPI de la configuración de la API de tu pasarela 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 pasarela aceptará las solicitudes que coincidan con la siguiente expresión regular:

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

Coincidencia con doble comodín

Si una ruta con plantilla contiene una variable denotada por un segmento de comodín doble (por ejemplo, {var=**}), la pasarela permitirá las solicitudes entrantes que cumplan 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 inclinada adicional al final de la ruta.

Nota: 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 porque {shelf=**} no se ha declarado 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 de la configuración de la API de tu pasarela puede contener una sección como la siguiente:

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

En este ejemplo, la pasarela aceptará las solicitudes que coincidan con la siguiente expresión regular:

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

Barras inclinadas codificadas como URL

API Gateway sigue el estándar RFC 3986, que no trata las barras inclinadas codificadas en URLs (%2F) como barras inclinadas reales al comparar las rutas de las URLs para tomar decisiones de enrutamiento o de seguridad. Si se esperan barras codificadas en la URL, su backend debe gestionar estas solicitudes en consecuencia.

Advertencia: Si tu backend espera que las barras inclinadas codificadas en URL (%2F) se traten como barras inclinadas reales al hacer coincidir plantillas de ruta de API Gateway, las solicitudes que contengan barras inclinadas codificadas en URL pueden coincidir con operaciones inesperadas y provocar un acceso con demasiados privilegios a los recursos del backend.

Por ejemplo, considere 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 tiene restricciones.

Si un usuario envía una solicitud a /shelves/shelf_1%2Fbooks%2Fbook_2:

• La pasarela procesará la solicitud como una operación GetShelf para el ID de estantería shelf_1%2Fbooks%2Fbook_2. En este caso, no se aplica la comprobación de la clave de API.
• Si el %2F se normaliza antes de que el backend gestione cualquier solicitud, la solicitud se puede procesar como la operación GetBook para el ID de libro book_2. Es decir, 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 comprobación de la clave de API en la pasarela. Sin embargo, como la pasarela ha leído la solicitud como una operación GetShelf, no se ha realizado ninguna comprobación de la clave de API.

Normalización de varias barras diagonales adyacentes

API Gateway sigue el estándar RFC 3986, que indica que las rutas con varias barras inclinadas adyacentes se tratarán como rutas diferentes a las que tienen barras inclinadas únicas. Por ejemplo, una solicitud que contenga /shelves/// no se normalizará en la pasarela a la ruta de solicitud /shelves/ antes de que coincida con una plantilla de ruta de URI ni al reenviarse al backend especificado.

Advertencia: Si tu backend normaliza las rutas de las URLs combinando varias barras diagonales en una sola, las solicitudes que contengan varias barras diagonales adyacentes pueden coincidir con operaciones de la pasarela inesperadas y pueden dar lugar a un acceso con demasiados privilegios a tus recursos de backend.