Memahami pembuatan template jalur

Dalam API Gateway, permintaan masuk dapat dirutekan berdasarkan pembuatan template jalur. Pembuatan template jalur memiliki tiga komponen utama:

  • Pencocokan persis
  • Pencocokan karakter pengganti tunggal
  • Pencocokan karakter pengganti ganda

Bagian berikut menjelaskan setiap komponen ini dan cara kerjanya dalam konteks API Gateway.

Pencocokan Persis

Jalur yang dibuat dengan template tanpa segmen karakter pengganti tunggal atau ganda (* atau **) akan dikonversi menjadi kecocokan jalur persis. Misalnya, spesifikasi OpenAPI untuk konfigurasi API gateway Anda dapat berisi bagian seperti berikut:

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

Dalam contoh ini, gateway akan hanya menerima permintaan ke /shelves dan tidak ada jalur lain.

Pencocokan Karakter Pengganti Tunggal

Jika jalur yang dibuat dengan template berisi variabel, segmen karakter pengganti tunggal ({var}), atau hanya di OpenAPI 2.0, segmen karakter pengganti tunggal ({var=*}), gateway akan mengizinkan permintaan masuk yang mematuhi hal berikut:

  • Permintaan tidak berisi garis miring tambahan (/), yang berarti variabel hanya akan cocok dengan satu segmen jalur.
  • Permintaan berisi setidaknya satu karakter.
  • Permintaan dapat berisi garis miring tambahan di akhir jika ada di akhir jalur.

Misalnya, spesifikasi OpenAPI untuk konfigurasi API gateway Anda dapat berisi bagian seperti berikut:

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

Dalam contoh ini, gateway akan menerima permintaan yang cocok dengan ekspresi reguler berikut:

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

Pencocokan Karakter Pengganti Ganda

Jika jalur yang dibuat dengan template berisi variabel yang ditandai dengan segmen karakter pengganti ganda (misalnya, {var=**}), gateway akan mengizinkan permintaan masuk yang mematuhi hal berikut:

  • Permintaan dapat berisi semua karakter, termasuk garis miring (/).
  • Permintaan dapat berisi 0 atau lebih karakter.
  • Permintaan dapat berisi garis miring tambahan di akhir jika ada di akhir jalur.

Misalnya, spesifikasi OpenAPI untuk konfigurasi API gateway Anda dapat berisi bagian seperti berikut:

OpenAPI 2.0

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

OpenAPI 3.x

...
paths:
  /shelves/{shelf}/books/{book}:
    get:
      summary: Retrieve a book
      parameters:
      - name: shelf
        in: path
        schema:
          type: string
      - name: book
        in: path
        schema:
          type: string
        x-google-parameter:
          pattern: '**'
...

Dalam contoh ini, gateway akan menerima permintaan dengan parameter book yang cocok dengan karakter apa pun, termasuk garis miring. Ini sesuai dengan ekspresi reguler berikut:

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

Garis Miring yang Dienkode URL

API Gateway mengikuti RFC 3986, yang tidak memperlakukan garis miring ke depan berenkode URL (%2F) sebagai garis miring sebenarnya saat mencocokkan jalur URL untuk keputusan perutean atau keamanan. Jika garis miring yang dienkode URL diharapkan, backend Anda harus menangani permintaan ini dengan tepat.

Misalnya, perhatikan spesifikasi OpenAPI berikut:

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

Dalam contoh ini, operasi /shelves/{shelf}/books/{book} memerlukan kunci API, tetapi operasi /shelves/{shelf} tidak dibatasi.

Jika pengguna mengirim permintaan ke /shelves/shelf_1%2Fbooks%2Fbook_2:

  • Gateway akan memproses permintaan sebagai operasi GetShelf untuk ID galeri shelf_1%2Fbooks%2Fbook_2. Dalam hal ini, pemeriksaan kunci API tidak diterapkan.
  • Jika %2F dinormalisasi sebelum penanganan permintaan oleh backend, permintaan tersebut dapat diproses sebagai operasi GetBook untuk ID buku book_2. Dengan kata lain, backend memproses /shelves/shelf_1%2Fbooks%2Fbook_2 sebagai /shelves/shelf_1/books/book_2.

Dalam contoh ini, backend mengharapkan operasi GetBook untuk melakukan pemeriksaan kunci API di gateway. Namun, karena gateway membaca permintaan sebagai operasi GetShelf, tidak ada pemeriksaan kunci API yang dilakukan.

Normalisasi Beberapa Garis Miring Berdekatan

API Gateway mengikuti RFC 3986, yang menyatakan bahwa jalur dengan beberapa garis miring ke depan yang berdekatan akan diperlakukan sebagai jalur yang berbeda dengan jalur yang memiliki garis miring ke depan tunggal.

Misalnya, permintaan yang berisi /shelves/// tidak akan dinormalisasi oleh gateway ke jalur permintaan /shelves/ sebelum mencocokkan template jalur URI atau saat meneruskan ke backend yang ditentukan.