Memahami pembuatan template jalur

Dalam Gateway API, permintaan masuk dapat dirutekan 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 Gateway API.

Pencocokan persis

Jalur yang dibuat dengan template tanpa segmen karakter pengganti tunggal atau ganda (* atau **) akan dikonversi menjadi pencocokan 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 hanya akan 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 ke depan (/) tambahan, yang berarti variabel hanya akan cocok dengan satu segmen jalur.
  • Permintaan berisi setidaknya satu karakter.
  • Permintaan dapat berisi garis miring di akhir tambahan 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 ke depan (/).
  • Permintaan dapat berisi 0 karakter atau lebih.
  • Permintaan dapat berisi garis miring di akhir tambahan 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 ke depan. Hal ini sesuai dengan ekspresi reguler berikut:

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

Garis miring ke depan yang dienkode URL

Gateway API mengikuti RFC 3986, yang tidak memperlakukan garis miring ke depan yang dienkode URL (%2F) sebagai garis miring yang sebenarnya saat mencocokkan jalur URL untuk keputusan perutean atau keamanan. Jika garis miring 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 mengirimkan 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 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 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 ke 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 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.

Aturan sintaksis

Gateway API menerapkan beberapa aturan validasi sintaksis untuk template jalur:

  • Konvensi Penamaan Variabel: Nama variabel harus diawali dengan huruf (kecil atau besar) atau garis bawah (_), dan hanya dapat berisi huruf, angka, garis bawah, titik (.), dan tanda hubung (-).
    • Valid: {my_var}, {var-1}, {var.name}
    • Tidak valid: {1var}, {my var}
  • Tidak Ada Campuran Parameter dan Literal: Satu segmen jalur tidak dapat berisi parameter dan karakter literal.
    • Valid: /prefix/{var}
    • Tidak valid: /prefix-{var}, /{var}suffix
  • Sufiks Metode Kustom yang Diizinkan: Satu-satunya pengecualian untuk mencampur parameter dan literal adalah di segmen terakhir jalur, tempat sufiks metode kustom yang dimulai dengan titik dua (:) diizinkan.
    • Valid: /{var}:customMethod
    • Tidak valid: /{var}:customMethod/suffix
  • Tidak Ada Beberapa Parameter per Segmen: Satu segmen jalur tidak dapat berisi lebih dari satu parameter.
    • Valid: /{var1}/{var2}
    • Tidak valid: /{var1}{var2}
  • Tidak Ada Parameter Bertingkat: Parameter tidak dapat bertingkat satu sama lain.
    • Valid: /{var}
    • Tidak valid: /{{var}}
  • Karakter Pengganti Ganda: Segmen karakter pengganti ganda hanya dapat berada di segmen jalur terakhir.
    • Valid: /prefix/{var=**}, /prefix/**
    • Tidak valid: /{var=**}/suffix, /**/suffix

Batas

Batas Nilai
Jumlah parameter per jalur 60
Panjang nama variabel 100
Panjang jalur (dengan atau tanpa pembuatan template) 512