Memahami Templating Jalur

Dalam API Gateway, Anda dapat merutekan permintaan masuk berdasarkan template jalur. 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 dengan template tanpa segmen karakter pengganti tunggal atau ganda (* atau **) akan dikonversi menjadi kecocokan jalur persis. Misalnya, spesifikasi OpenAPI untuk konfigurasi API gateway Anda mungkin 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 dengan template berisi variabel, segmen karakter pengganti tunggal (misalnya {var} atau {var=*}), atau keduanya, 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 minimal satu karakter.
  • Permintaan dapat berisi garis miring akhir tambahan jika ada di akhir jalur.

Misalnya, spesifikasi OpenAPI untuk konfigurasi API gateway 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 dengan template berisi variabel yang dilambangkan 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 beberapa karakter.
  • Permintaan dapat berisi garis miring akhir tambahan jika ada di akhir jalur.

Misalnya, spesifikasi OpenAPI untuk konfigurasi API gateway 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 Miring Depan yang Dienkode URL

API Gateway mengikuti RFC 3986, yang tidak memperlakukan garis miring ke depan (%2F) yang dienkode URL sebagai garis miring yang sebenarnya saat mencocokkan jalur URL untuk keputusan pemilihan rute atau keamanan. Jika slash yang dienkode URL diharapkan, 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 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 Depan yang 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 satu garis miring ke depan. Misalnya, permintaan yang berisi /shelves/// tidak akan dinormalisasi oleh gateway ke jalur permintaan /shelves/ sebelum mencocokkan template jalur URI atau setelah diteruskan ke backend yang ditentukan.