Objek OpenAPI JSON sebagai Parameter Kueri

1. Ikhtisar

Dalam tutorial ini, kita akan mempelajari cara bekerja dengan objek JSON sebagai parameter kueri menggunakan OpenAPI .

2. Parameter Query di OpenAPI 2

OpenAPI 2 tidak mendukung objek sebagai parameter kueri ; hanya nilai primitif dan array primitif yang didukung.

Karena itu, kita akan ingin mendefinisikan parameter JSON kita sebagai string.

Untuk melihatnya beraksi, mari tentukan parameter yang disebut params sebagai string , meskipun kita akan menguraikannya sebagai JSON di backend kita:

swagger: "2.0" ... paths: /tickets: get: tags: - "tickets" summary: "Send an JSON Object as a query param" parameters: - name: "params" in: "path" description: "{\"type\":\"foo\",\"color\":\"green\"}" required: true type: "string" 

Jadi, alih-alih:

GET //localhost:8080/api/tickets?type=foo&color=green

kami akan melakukan:

GET //localhost:8080/api/tickets?params={"type":"foo","color":"green"}

3. Parameter Query di OpenAPI 3

OpenAPI 3 memperkenalkan dukungan untuk objek sebagai parameter kueri.

Untuk menentukan parameter JSON, kita perlu menambahkan bagian konten ke definisi kita yang menyertakan tipe dan skema MIME:

openapi: 3.0.1 ... paths: /tickets: get: tags: - tickets summary: Send an JSON Object as a query param parameters: - name: params in: query description: '{"type":"foo","color":"green"}' required: true schema: type: object properties: type: type: "string" color: type: "string" 

Permintaan kami sekarang dapat terlihat seperti:

GET //localhost:8080/api/tickets?params[type]=foo¶ms[color]=green

Dan sebenarnya, itu masih bisa terlihat seperti:

GET //localhost:8080/api/tickets?params={"type":"foo","color":"green"}

Opsi pertama memungkinkan kita untuk menggunakan validasi parameter, yang akan memberi tahu kita jika ada yang salah sebelum permintaan dibuat.

Dengan opsi kedua, kami memperdagangkannya untuk kontrol yang lebih besar pada backend serta kompatibilitas OpenAPI 2.

4. Pengkodean URL

Penting untuk diperhatikan bahwa, dalam membuat keputusan ini untuk mengangkut parameter permintaan sebagai objek JSON, kami ingin meng-encode parameter URL untuk memastikan pengangkutan yang aman.

Jadi, untuk mengirim URL berikut:

GET /tickets?params={"type":"foo","color":"green"}

Kami sebenarnya akan melakukan:

GET /tickets?params=%7B%22type%22%3A%22foo%22%2C%22color%22%3A%22green%22%7D

5. Batasan

Selain itu, perhatikan batasan dalam meneruskan objek JSON sebagai sekumpulan parameter kueri:

  • keamanan berkurang
  • panjang parameter yang terbatas

Misalnya, semakin banyak data yang kami tempatkan di parameter kueri , semakin banyak yang muncul di log server dan semakin tinggi potensi keterpaparan data sensitif.

Selain itu, satu parameter kueri tidak boleh lebih dari 2048 karakter. Tentu, kita semua bisa membayangkan skenario di mana objek JSON kita lebih besar dari itu. Secara praktis, pengkodean URL dari string JSON kami sebenarnya akan membatasi kami hingga sekitar 1000 karakter untuk muatan kami.

Salah satu solusinya adalah mengirim Objek JSON yang lebih besar ke dalam isi. Dengan cara ini, kami memperbaiki masalah keamanan dan batasan panjang JSON.

Sebenarnya, GET atau POST keduanya mendukung ini. Salah satu alasan untuk mengirim badan melalui GET adalah untuk mempertahankan semantik RESTful dari API kami.

Tentu saja, ini agak tidak biasa dan tidak didukung secara universal. Misalnya, beberapa pustaka HTTP JavaScript tidak mengizinkan permintaan GET memiliki badan permintaan.

Singkatnya, pilihan ini merupakan trade-off antara semantik dan kompatibilitas universal.

6. Kesimpulan

Singkatnya, dalam artikel ini kita mempelajari cara menentukan objek JSON sebagai parameter kueri menggunakan OpenAPI. Kemudian, kami mengamati beberapa implikasi di bagian belakang.

Definisi OpenAPI lengkap untuk contoh-contoh ini tersedia di GitHub.