경로 템플릿 이해
API 게이트웨이 내에서는 경로 템플릿을 기반으로 수신 요청을 라우팅할 수 있습니다. 경로 템플릿에는 다음 세 가지 기본 구성요소가 포함됩니다.
- 완전 일치 검색
- 단일 와일드 카드 일치
- 이중 와일드 카드 일치
다음 섹션에서는 이러한 각 구성요소와 API 게이트웨이의 컨텍스트 내에서 각 구성요소의 작동 방식에 대해 설명합니다.
완전 일치 검색
단일 또는 이중 와일드 카드 세그먼트(*
또는 **
)가 없는 템플릿 경로는 완전 일치 경로로 변환됩니다.
예를 들어 게이트웨이 API 구성의 OpenAPI 사양에 다음과 같은 섹션이 포함될 수 있습니다.
...
paths:
/shelves:
get:
summary: List shelves
...
이 예시에서 게이트웨이는 /shelves
에 대해서만 요청을 수락하고 다른 경로에 대해서는 요청을 수락하지 않습니다.
단일 와일드 카드 일치
템플릿 경로에 변수나 단일 와일드 카드 세그먼트(예: {var}
또는 {var=*}
)가 포함되었거나 둘 다 포함된 경우에는 게이트웨이에서 다음과 호환되는 수신 요청이 허용됩니다.
- 요청에 추가적인 정방향 슬래시(
/
)가 없습니다. 즉, 변수가 단일 경로 세그먼트와만 일치합니다. - 요청에 하나 이상의 문자가 포함됩니다.
- 경로 끝에 있는 경우 요청에 추가적인 후행 슬래시가 포함될 수 있습니다.
예를 들어 게이트웨이 API 구성의 OpenAPI 사양에 다음과 같은 섹션이 포함될 수 있습니다.
...
paths:
/shelves/{shelf}/books/{book}: # Equivalent to /shelves/{shelf=*}/books/{book=*}
get:
summary: Retrieve a book
...
이 예시에서 게이트웨이는 다음 정규식과 일치하는 요청을 수락합니다.
^/shelves/[^/]+/books/[^/]+/?$
이중 와일드 카드 일치
템플릿 경로에 이중 와일드 카드 세그먼트(예: {var=**}
)로 표시된 변수가 포함된 경우 게이트웨이에서 다음과 호환된 수신 요청이 허용됩니다.
- 정방향 슬래시(/)를 포함하여 모든 문자가 요청에 포함될 수 있습니다.
- 요청에 0개 또는 그 이상의 문자가 포함될 수 있습니다.
- 경로 끝에 있는 경우 요청에 추가적인 후행 슬래시가 포함될 수 있습니다.
예를 들어 게이트웨이 API 구성의 OpenAPI 사양에 다음과 같은 섹션이 포함될 수 있습니다.
...
paths:
/shelves/{shelf=*}/books/{book=**}:
get:
summary: Retrieve a book
...
이 예시에서 게이트웨이는 다음 정규식과 일치하는 요청을 수락합니다.
^/shelves/[^/]+/books/.*/?$
URL 인코딩 정방향 슬래시
API 게이트웨이는 라우팅 및 보안 결정을 위해 일치하는 URL 경로를 검색할 때 URL 인코딩 정방향 슬래시(%2F
)를 실제 슬래시로 취급하지 않는 RFC 3986을 따릅니다. URL 인코딩 슬래시가 필요하면 백엔드가 그에 맞게 이러한 요청을 처리해야 합니다.
예를 들어 다음 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: []
이 예시에서 /shelves/{shelf}/books/{book}
연산에는 API 키가 필요하지만 /shelves/{shelf}
연산은 제한이 없습니다.
사용자가 /shelves/shelf_1%2Fbooks%2Fbook_2
에 요청을 보내는 경우:
- 게이트웨이가 요청을 서가 ID
shelf_1%2Fbooks%2Fbook_2
에 대한GetShelf
연산으로 처리합니다. 이 경우 API 키 확인이 적용되지 않습니다. - 백엔드에서 요청을 처리하기 전
%2F
가 정규화된 경우에는 요청이 대신 서적 IDbook_2
에 대한GetBook
연산으로 처리될 수 있습니다. 즉, 백엔드가/shelves/shelf_1%2Fbooks%2Fbook_2
를/shelves/shelf_1/books/book_2
로 처리합니다.
이 예시에서 백엔드는 GetBook
연산이 게이트웨이에서 API 키 확인을 수행할 것으로 예상합니다. 하지만 게이트웨이가 요청을 GetShelf
연산으로 읽기 때문에 API 키 확인이 수행되지 않습니다.
여러 인접한 정방향 슬래시의 정규화
API 게이트웨이는 여러 인접한 정방향 슬래시가 있는 경로가 단일 정방향 슬래시가 있는 경로와 다른 경로로 취급되도록 지정하는 RFC 3986을 따릅니다.
예를 들어 /shelves///
가 포함된 요청은 일치하는 URI 경로 템플릿을 검색하기 전이나 지정된 백엔드로 전달된 후 중 어느 경우에도 요청 경로 /shelves/
로 게이트웨이에서 정규화되지 않습니다.