경로 템플릿 이해

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가 정규화된 경우에는 요청이 대신 서적 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/로 게이트웨이에서 정규화되지 않습니다.