Memahami Templating Jalur

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

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

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

Pencocokan Persis

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

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

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

Pencocokan Karakter Pengganti Tunggal

Jika jalur dengan template berisi variabel, segmen karakter pengganti tunggal (misalnya {var} atau {var=*}), atau keduanya, gateway akan mengizinkan permintaan masuk yang sesuai dengan hal berikut:

  • Permintaan tersebut 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 jika ada di akhir jalur.

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

...
paths:
  /shelves/{shelf}/books/{book}: # Equivalent to /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 template berisi variabel yang ditunjukkan oleh segmen karakter pengganti ganda (misalnya {var=**}), gateway akan mengizinkan permintaan masuk yang sesuai dengan hal berikut:

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

Misalnya, spesifikasi OpenAPI untuk konfigurasi gateway API Anda mungkin 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/.*/?$

Garis Garis Depan URL yang Dienkode

Gateway API mengikuti RFC 3986, yang tidak memperlakukan garis miring ke depan yang dienkode ke URL (%2F) sebagai garis miring yang sebenarnya saat mencocokkan jalur URL untuk keputusan pemilihan rute atau keamanan. Jika ada garis miring yang dienkode ke URL, backend Anda harus menangani permintaan ini sebagaimana mestinya.

Misalnya, pertimbangkan 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 rak shelf_1%2Fbooks%2Fbook_2. Dalam hal ini, pemeriksaan kunci API tidak diterapkan.
  • Jika %2F dinormalisasi sebelum penanganan permintaan apa pun oleh backend, permintaan tersebut mungkin akan 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 melakukan pemeriksaan kunci API di gateway. Namun, karena gateway membaca permintaan sebagai operasi GetShelf, tidak ada pemeriksaan kunci API yang dilakukan.

Normalisasi Beberapa Garis Garis Depan yang Berdekatan

Gateway API mengikuti RFC 3986, yang menyatakan bahwa jalur dengan beberapa garis miring ke depan yang berdekatan akan diperlakukan sebagai jalur yang berbeda dari jalur dengan garis miring tunggal ke depan. Misalnya, permintaan yang berisi /shelves/// tidak akan dinormalisasi oleh gateway ke jalur permintaan /shelves/ sebelum mencocokkan template jalur URI nor setelah meneruskan ke backend yang ditentukan.