Understanding Path Templating

Within API Gateway, it is possible to route incoming requests based on path templating. Path templating has three main components:

• Exact match
• Single wildcard match
• Double wildcard match

The following sections describe each of these components and how they work within the context of API Gateway.

Exact Match

A templated path without any single or double wildcard segments (* or **) is converted to an exact path match. For example, the OpenAPI spec for your gateway API config may contain a section like the following:

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

In this example, the gateway will only accept requests to /shelves and no other paths.

Note: URL-encoded forward slashes (%2F) will not be treated as actual forward slashes, meaning %2Fshelves will not match the above OpenAPI operation.

Single Wildcard Matching

If a templated path contains a variable, a singular wildcard segment (e.g {var} or {var=*}), or both, the gateway will allow incoming requests that comply with the following:

• The requests do not contain an additional forward slash (/), meaning the variable will only match a single path segment.
• The requests contain at least one character.
• The requests may contain an additional trailing slash if present at the end of the path.

Note: For variable expansion, all characters except [-_.~/0-9a-zA-Z] are percent-encoded.

For example, the OpenAPI spec for your gateway API config may contain a section like the following:

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

In this example, the gateway will accept requests that match the following regex:

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

Double Wildcard Matching

If a templated path contains a variable denoted by a double wildcard segment (e.g {var=**}), the gateway will allow incoming requests that comply with the following:

• The requests can contain all characters, including forward slashes (/).
• The requests can contain 0 or more characters.
• The requests may contain an additional trailing slash if present at the end of the path.

Note: Double wildcard variables can only be used in the last segment of the provided path. This means that /shelves/{shelf=**}/books/{book=**} is not allowed, because {shelf=**} is not declared in the last segment of the path. For variable expansion, all characters except [-_.~/0-9a-zA-Z] are percent-encoded.

For example, the OpenAPI spec for your gateway API config may contain a section like the following:

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

In this example, the gateway will accept requests that match the following regex:

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

URL Encoded Forward Slashes

API Gateway follows RFC 3986, which does not treat URL encoded forward slashes (%2F) as actual slashes when matching URL paths for routing or security decisions. If URL encoded slashes are expected, your backend should handle these requests accordingly.

Warning: If your backend expects URL encoded forward slashes (%2F) to be treated as actual slashes when matching API Gateway path templates, then requests containing URL encoded forward slashes may match unexpected operations and result in over-privileged access to backend resources.

For example, consider the following OpenAPI spec:

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: []

In this example, the /shelves/{shelf}/books/{book} operation requires an API key, but the /shelves/{shelf} operation is unrestricted.

In the event that a user sends a request to /shelves/shelf_1%2Fbooks%2Fbook_2:

• The gateway will process the request as a GetShelf operation for the shelf ID shelf_1%2Fbooks%2Fbook_2. In this case, an API key check is not enforced.
• If the %2F is normalized before any request handling by the backend, the request may instead be processed as the GetBook operation for the book ID book_2. In other words, the backend processes /shelves/shelf_1%2Fbooks%2Fbook_2 as /shelves/shelf_1/books/book_2.

In this example, the backend expects the GetBook operation to perform an API key check at the gateway. However, because the gateway read the request as a GetShelf operation, no API key check was performed.

Normalization of Multiple Adjacent Forward Slashes

API Gateway follows RFC 3986, which states that paths with multiple adjacent forward slashes will be treated as a different path than those with singular forward slashes. For instance, a request containing /shelves/// will not be normalized by the gateway to the request path /shelves/ prior to matching a URI path template nor upon forwarding to the specified backend.

Warning: If your backend normalizes URL paths by merging multiple forward slashes to a single slash, then requests containing multiple adjacent forward slashes may match unexpected gateway operations and may result in over-privileged access to your backend resources.