이 예시에서 /shelves/{shelf}/books/{book} 연산에는 API 키가 필요하지만 /shelves/{shelf} 연산은 제한이 없습니다.
사용자가 /shelves/shelf_1%2Fbooks%2Fbook_2에 요청을 보내는 경우:
게이트웨이가 요청을 서가 ID shelf_1%2Fbooks%2Fbook_2에 대한 GetShelf 연산으로 처리합니다. 이 경우 API 키 확인이 적용되지 않습니다.
백엔드에서 요청을 처리하기 전 %2F가 정규화된 경우에는 요청이 대신 서적 ID book_2에 대한 GetBook 연산으로 처리될 수 있습니다. 즉, 백엔드가 /shelves/shelf_1%2Fbooks%2Fbook_2를 /shelves/shelf_1/books/book_2로 처리합니다.
이 예시에서 백엔드는 GetBook 연산이 게이트웨이에서 API 키 확인을 수행할 것으로 예상합니다. 하지만 게이트웨이가 요청을 GetShelf 연산으로 읽기 때문에 API 키 확인이 수행되지 않습니다.
여러 인접한 정방향 슬래시의 정규화
API 게이트웨이는 여러 인접한 정방향 슬래시가 있는 경로가 단일 정방향 슬래시가 있는 경로와 다른 경로로 취급되도록 지정하는 RFC 3986을 따릅니다.
예를 들어 /shelves///가 포함된 요청은 일치하는 URI 경로 템플릿을 검색하기 전이나 지정된 백엔드로 전달된 후 중 어느 경우에도 요청 경로 /shelves/로 게이트웨이에서 정규화되지 않습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-03(UTC)"],[[["\u003cp\u003eAPI Gateway uses path templating to route incoming requests, with three main components: exact match, single wildcard match, and double wildcard match.\u003c/p\u003e\n"],["\u003cp\u003eExact match path templates only accept requests that precisely match the defined path, with URL-encoded forward slashes not being treated as actual forward slashes.\u003c/p\u003e\n"],["\u003cp\u003eSingle wildcard matches accept requests with at least one character in the specified variable, no additional forward slashes within the variable, and an optional trailing slash.\u003c/p\u003e\n"],["\u003cp\u003eDouble wildcard matches accept requests with zero or more characters, including forward slashes, but the variable must be the last segment of the path and URL-encoded characters are handled appropriately.\u003c/p\u003e\n"],["\u003cp\u003eAPI Gateway does not normalize URL-encoded forward slashes (\u003ccode\u003e%2F\u003c/code\u003e) or multiple adjacent forward slashes, potentially leading to unexpected routing or security vulnerabilities if the backend handles them differently.\u003c/p\u003e\n"]]],[],null,["# Understanding Path Templating\n=============================\n\nWithin API Gateway, it is possible to route incoming requests based on [path templating](https://cloud.google.com/endpoints/docs/grpc-service-config/reference/rpc/google.api#path-template-syntax).\nPath templating has three main components:\n\n- Exact match\n- Single wildcard match\n- Double wildcard match\n\nThe following sections describe each of these components and how they work within the context of API Gateway.\n\nExact Match\n-----------\n\nA templated path *without* any single or double wildcard segments (`*` or `**`) is converted to an exact path match.\nFor example, the OpenAPI spec for your gateway API config may contain a section like the following: \n\n ...\n paths:\n /shelves:\n get:\n summary: List shelves\n ...\n\nIn this example, the gateway will *only* accept requests to `/shelves` and no other paths.\n| **Note:** URL-encoded forward slashes (`%2F`) will not be treated as actual forward slashes, meaning `%2Fshelves` will *not* match the above OpenAPI operation.\n\nSingle Wildcard Matching\n------------------------\n\nIf 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:\n\n- The requests do not contain an additional forward slash (`/`), meaning the variable will only match a single path segment.\n- The requests contain at least one character.\n- The requests may contain an additional trailing slash if present at the end of the path.\n\n| **Note:** For variable expansion, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.\n\nFor example, the OpenAPI spec for your gateway API config may contain a section like the following: \n\n ...\n paths:\n /shelves/{shelf}/books/{book}: # Equivalent to /shelves/{shelf=*}/books/{book=*}\n get:\n summary: Retrieve a book\n ...\n\nIn this example, the gateway will accept requests that match the following regex: \n\n ^/shelves/[^/]+/books/[^/]+/?$\n\nDouble Wildcard Matching\n------------------------\n\nIf a templated path contains a variable denoted by a double wildcard segment (e.g `{var=**}`),\nthe gateway will allow incoming requests that comply with the following:\n\n- The requests can contain *all* characters, including forward slashes (/).\n- The requests can contain 0 or more characters.\n- The requests may contain an additional trailing slash if present at the end of the path.\n\n| **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.\n\nFor example, the OpenAPI spec for your gateway API config may contain a section like the following: \n\n ...\n paths:\n /shelves/{shelf=*}/books/{book=**}:\n get:\n summary: Retrieve a book\n ...\n\nIn this example, the gateway will accept requests that match the following regex: \n\n ^/shelves/[^/]+/books/.*/?$\n\nURL Encoded Forward Slashes\n---------------------------\n\nAPI Gateway follows [RFC 3986](https://tools.ietf.org/html/rfc3986), 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.\n| **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.\n\nFor example, consider the following OpenAPI spec: \n\n securityDefinitions:\n api_key:\n type: \"apiKey\"\n name: \"key\"\n in: \"query\"\n paths:\n /shelves/{shelf}:\n get:\n parameters:\n - in: path\n name: shelf\n type: string\n required: true\n description: Shelf ID.\n summary: List shelves\n operationId: GetShelf\n responses:\n '200':\n description: A successful response\n schema:\n type: string\n /shelves/{shelf}/books/{book}:\n get:\n parameters:\n - in: path\n name: shelf\n type: string\n required: true\n description: Shelf ID.\n - in: path\n name: book\n type: string\n required: true\n description: Book ID\n summary: Retrieve a book\n operationId: GetBook\n responses:\n '200':\n description: A successful response\n schema:\n type: string\n security:\n - api_key: []\n\nIn this example, the `/shelves/{shelf}/books/{book}` operation requires an API key, but the `/shelves/{shelf}` operation is unrestricted.\n\nIn the event that a user sends a request to `/shelves/shelf_1%2Fbooks%2Fbook_2`:\n\n- 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**.\n- 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`.\n\nIn 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**.\n\nNormalization of Multiple Adjacent Forward Slashes\n--------------------------------------------------\n\nAPI Gateway follows [RFC 3986](https://tools.ietf.org/html/rfc3986), which states that paths with multiple adjacent forward slashes will be treated as a different path than those with singular forward slashes.\nFor 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.\n| **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."]]
