Menyematkan Nilai dalam URL Dokumentasi

Tingkatkan kolaborasi dengan menyematkan nilai parameter dan variabel tertentu secara langsung dalam URL dokumentasi yang dibagikan. Secara default, dokumen yang dibagikan hanya berisi spesifikasi API. Fitur ini memungkinkan Anda membagikan nilai yang telah diisi sebelumnya, sehingga memudahkan pengguna untuk menguji endpoint dengan konfigurasi tertentu.

Perilaku Parameter

Nilai parameter yang diteruskan melalui URL berperilaku berbeda berdasarkan jenisnya:

Variabel Lingkungan: Nilai yang ditetapkan melalui URL diterapkan secara global pada semua endpoint dalam dokumen. Nilai tersebut tetap ada saat berpindah antar-endpoint atau membuka tab baru, dan tetap aktif hingga secara eksplisit ditimpa atau diubah secara manual

Parameter Permintaan (Query, Path, Body, Header, Cookie): Nilai ini dibatasi pada endpoint tertentu yang diakses melalui URL dan tidak tetap ada saat berpindah ke endpoint lain

Meneruskan Nilai Parameter

Tersedia dua metode untuk menyematkan nilai parameter: Mode Sederhana dan Mode Kompleks. Mode Sederhana lebih ringkas dan tidak memerlukan pengodean URL, tetapi tidak dapat menangani karakter tanda kurung siku. Mode Kompleks mendukung semua karakter tetapi memerlukan pengodean URL untuk data parameter.

Mode Sederhana

Mode Sederhana menggunakan format parameterType[parameterName]=value.

Contoh:

https://apidog.com/apidoc/docs-site/538323/api-7312738-run?environment[access_token]=example_value&query[locale]=en-US

Jenis Parameter	Format Nilai Parameter	Deskripsi	Perilaku
Parameter Query	`query[xxx]=yyy`		Hanya endpoint saat ini
Parameter Path	`path[xxx]=yyy`		Hanya endpoint saat ini
Parameter Body	`body[xxx]=yyy`	Untuk jenis body `form-data` atau `x-www-form-urlencoded`	Hanya endpoint saat ini
Parameter Body	`body=yyy`	Untuk jenis body lainnya (misalnya, JSON mentah, XML)	Hanya endpoint saat ini
Parameter Header	`header[xxx]=yyy`		Hanya endpoint saat ini
Parameter Cookie	`cookie[xxx]=yyy`		Hanya endpoint saat ini
Variabel Lingkungan	`environment[xxx]=yyy`	Menetapkan nilai dalam lingkungan default.	Tetap ada lintas endpoint

Mode Kompleks

Mode Kompleks meneruskan objek JSON yang dikodekan URL sebagai nilai dari parameter params. Objek JSON ini harus dikodekan menggunakan encodeURIComponent. Dalam JavaScript, hal ini dapat dilakukan dengan: encodeURIComponent(JSON.stringify({"query":["id",1]})).

Contoh JSON (sebelum pengodean):

{
    "query": [
        ["id", "value1"],
        ["id", "value2"],
        ["key2", "value3"]
    ],
    "path": [
        ["key1", "value1"],
        ["key2", "value2"]
    ],
    "body": [
        ["aaa", "value1"],
        ["key2", "value2"]
    ],
    "header": [
        ["testHeader", "value1"],
        ["key2", "value2"]
    ],
    "cookie": [
        ["testCookie", "value1"],
        ["key2", "value2"]
    ],
    "environment": [
        ["access_token", "example_value"],
        ["projectId", "1"]
    ]
}

Contoh URL (setelah pengodean):

https://apidog.com/apidoc/docs-site/538323/api-7312738-run?params=%7B%22query%22%3A%5B%5B%22id%22%2C%22value1%22%5D%2C%5B%22id%22%2C%22value2%22%5D%2C%5B%22key2%22%2C%22value3%22%5D%5D%2C%22path%22%3A%5B%5B%22key1%22%2C%22value1%22%5D%2C%5B%22key2%22%2C%22value2%22%5D%5D%2C%22body%22%3A%5B%5B%22aaa%22%2C%22value1%22%5D%2C%5B%22key2%22%2C%22value2%22%5D%5D%2C%22header%22%3A%5B%5B%22testHeader%22%2C%22value1%22%5D%2C%5B%22key2%22%2C%22value2%22%5D%5D%2C%22cookie%22%3A%5B%5B%22testCookie%22%2C%22value1%22%5D%2C%5B%22key2%22%2C%22value2%22%5D%5D%2C%22environment%22%3A%5B%5B%22access_token%22%2C%22example_value%22%5D%2C%5B%22projectId%22%2C%221%22%5D%5D%7D

Jenis Parameter	Nilai Parameter	Deskripsi	Perilaku
Parameter Query	`query`	Array pasangan kunci-nilai.	Hanya endpoint saat ini
Parameter Path	`path`	Array pasangan kunci-nilai.	Hanya endpoint saat ini
Parameter Body	`body`	Array pasangan kunci-nilai untuk `form-data` atau `x-www-form-urlencoded`; string untuk jenis body lainnya.	Hanya endpoint saat ini
Parameter Header	`header`	Array pasangan kunci-nilai.	Hanya endpoint saat ini
Parameter Cookie	`cookie`	Array pasangan kunci-nilai.	Hanya endpoint saat ini
Variabel Lingkungan	`environment`	Array pasangan kunci-nilai. Menetapkan nilai dalam lingkungan default.	Tetap ada lintas endpoint

Meneruskan Variabel Lingkungan

Untuk secara otomatis menetapkan variabel lingkungan bagi pengguna, sertakan variabel tersebut dalam URL. Variabel ini akan tetap ada di semua endpoint dalam dokumen.

Contoh:

https://openapi.apidog.io/api-7312738-run?environment[access_token]=example_value

Praktik Terbaik

Variabel lingkungan tetap ada lintas endpoint, sementara jenis parameter lainnya (query, path, body, header, cookie) dibatasi pada endpoint tertentu dalam URL. Metode ini paling sesuai untuk membagikan nilai yang dapat digunakan kembali di beberapa endpoint.

Menyematkan Nilai dalam URL Dokumentasi

Perilaku Parameter#

Meneruskan Nilai Parameter#

Mode Sederhana#

Mode Kompleks#

Meneruskan Variabel Lingkungan#

Perilaku Parameter

Meneruskan Nilai Parameter

Mode Sederhana

Mode Kompleks

Meneruskan Variabel Lingkungan