DEV Community

Cover image for Cara Mengatur Parameter Global di Apidog (Kirim Header Otentikasi Otomatis di Setiap Permintaan)
Walse
Walse

Posted on • Originally published at apidog.com

Cara Mengatur Parameter Global di Apidog (Kirim Header Otentikasi Otomatis di Setiap Permintaan)

Anda memiliki 40 endpoint dalam satu proyek, dan setiap endpoint memerlukan header Authorization: Bearer ... serta X-Api-Version. Menambahkan keduanya secara manual ke setiap request memang lambat dan rawan inkonsistensi: satu endpoint memakai token yang benar, endpoint lain terlupakan, lalu error 401 hanya muncul pada beberapa rute.

Coba Apidog sekarang

Dengan Apidog, Anda dapat mendefinisikan parameter sekali lalu menerapkannya otomatis ke request yang sesuai. Artikel ini membahas tiga pendekatan:

  1. Parameter global untuk seluruh proyek.
  2. Variabel lingkungan untuk menyimpan token.
  3. Skrip pra-permintaan pada folder untuk header dengan cakupan terbatas.

Untuk pembahasan variabel yang lebih mendalam, baca panduan menguasai variabel di Apidog.

Konsep ini mengikuti pola header HTTP standar: pasangan key/value yang dikirim bersama request, seperti dijelaskan dalam referensi header HTTP MDN. Perbedaannya, Apidog memungkinkan Anda mengelola header tersebut dari satu tempat.

Apa Arti “Parameter Global”?

Parameter global di Apidog adalah parameter request yang berlaku pada seluruh proyek, bukan hanya pada satu endpoint. Setelah didefinisikan, Apidog akan melampirkannya ke request yang cocok secara otomatis.

Parameter global tersedia untuk empat lokasi:

  • Headers — untuk Authorization, X-Api-Version, dan header lain.
  • Cookies — untuk cookie sesi.
  • Query — untuk nilai seperti ?api_key=....
  • Body — untuk field yang harus ada pada body request.

Untuk autentikasi bearer token, gunakan Headers.

Parameter global memiliki prioritas lebih rendah daripada parameter pada endpoint. Jika endpoint sudah mendefinisikan header Authorization, nilai endpoint tersebut akan digunakan.

Dengan kata lain, parameter global berfungsi sebagai default proyek, bukan penimpaan paksa.

Atur Header Global untuk Semua Request

Targetnya adalah menambahkan header berikut ke semua endpoint tanpa mengedit endpoint satu per satu:

Authorization: Bearer {{token}}
X-Api-Version: 2024-08-01
Enter fullscreen mode Exit fullscreen mode

Langkah 1: Buka Manajemen Lingkungan

Buka Manajemen Lingkungan dari bagian kanan atas halaman Apidog.

Area ini digunakan untuk mengelola parameter yang berlaku di seluruh proyek. Lihat juga dokumentasi Apidog untuk referensi konfigurasi parameter dan environment.

Langkah 2: Pilih Headers

Pilih lokasi Headers atau Header Permintaan.

Gunakan lokasi lain hanya jika nilai default Anda memang harus dikirim sebagai cookie, query parameter, atau body parameter.

Langkah 3: Tambahkan Header Authorization

Tambahkan parameter global pertama dengan konfigurasi berikut:

Properti Nilai
Name Authorization
Type string
Default Value Bearer {{token}}
Description Bearer token untuk semua endpoint yang diautentikasi.

Jangan menyimpan token mentah langsung pada Default Value. Gunakan {{token}} agar token diambil dari variabel.

Langkah 4: Tambahkan Header Versi API

Tambahkan parameter global kedua:

Properti Nilai
Name X-Api-Version
Type string
Default Value 2024-08-01
Description Versi API yang dipatok untuk setiap request.

Langkah 5: Aktifkan dan Simpan

Aktifkan sakelar pada setiap parameter, lalu simpan konfigurasi.

Setelah tersimpan, setiap request dalam proyek akan membawa header berikut, kecuali endpoint tersebut mendefinisikan nilai header sendiri:

Authorization: Bearer {{token}}
X-Api-Version: 2024-08-01
Enter fullscreen mode Exit fullscreen mode

Langkah 6: Verifikasi Header yang Terkirim

Jangan hanya mengandalkan konfigurasi. Kirim request apa pun, lalu buka tab Actual Request di konsol respons.

Tab ini menunjukkan request persis seperti yang dikirim, setelah variabel diganti dengan nilai aslinya.

GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01
Enter fullscreen mode Exit fullscreen mode

Jika kedua header terlihat di Actual Request, berarti konfigurasi Anda sudah diterapkan.

Simpan Token dengan Variabel, Bukan Teks Biasa

Nilai berikut:

Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

lebih aman daripada:

Bearer sk_live_7f3a9c2e1b8d4056
Enter fullscreen mode Exit fullscreen mode

Sintaks {{token}} merujuk ke variabel. Header bearer sendiri mengikuti skema yang dijelaskan pada RFC 6750, sedangkan cara server membaca header tersebut dapat dilihat di referensi Authorization MDN.

Buat Variabel token

  1. Klik ikon environment ≡ di kanan atas.
  2. Buka bagian Global Variables.
  3. Tambahkan variabel bernama token.
  4. Isi nilainya dengan bearer token Anda.
  5. Klik Save.

Header global Anda tetap menggunakan:

Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Saat request dikirim, Apidog akan menggantinya menjadi:

Bearer <your-real-secret>
Enter fullscreen mode Exit fullscreen mode

Gunakan tab Actual Request untuk memastikan substitusi variabel berjalan seperti yang diharapkan.

Pola yang disarankan:

  • Parameter global menyimpan struktur header.
  • Variabel environment menyimpan nilai rahasia.

Untuk praktik pengelolaan token yang lebih lengkap, baca panduan manajemen environment dan rahasia klien API.

Ganti Token per Environment

Dalam proyek nyata, Anda biasanya memiliki beberapa environment:

  • Development
  • Testing
  • Production

Setiap environment dapat menyimpan nilai token yang berbeda. Pilih environment melalui dropdown Lingkungan di dekat ikon ≡.

Header global tidak perlu diubah:

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Yang berubah hanya nilai token berdasarkan environment aktif.

Jika Anda juga mengatur bearer auth, API key, atau OAuth, lihat panduan skema keamanan Apidog.

Menambahkan Header Hanya pada Satu Folder

Parameter global berlaku untuk seluruh proyek. Jika Anda hanya perlu header pada folder tertentu, gunakan skrip pra-permintaan di folder tersebut.

Contoh: hanya endpoint dalam folder /admin yang memerlukan X-Admin-Scope.

Apidog tidak menyediakan field header bawaan pada pengaturan folder. Sebagai gantinya, tambahkan skrip pra-permintaan berikut pada folder:

pm.request.headers.add({
  key: 'X-Admin-Scope',
  value: 'full'
});
Enter fullscreen mode Exit fullscreen mode

Setiap request dalam folder akan menerima header tersebut, sedangkan request di luar folder tidak akan terpengaruh.

Gunakan pendekatan ini untuk kebutuhan header dengan cakupan folder. Untuk detail skrip pm.*, lihat panduan skrip pra-permintaan dan pasca-permintaan di Apidog.

Pilih Pendekatan Berdasarkan Cakupan

Kebutuhan Pendekatan
Header berlaku untuk semua endpoint Parameter global di Headers
Token berbeda pada Development, Testing, dan Production Variabel environment seperti {{token}}
Header hanya berlaku untuk satu kelompok endpoint Skrip pra-permintaan tingkat folder

Beberapa hal yang perlu diperiksa:

  • Hindari nama parameter global yang duplikat.
  • Pastikan tipe parameter sesuai dengan penggunaannya.
  • Ingat bahwa nilai header pada endpoint akan mengalahkan nilai parameter global.
  • Gunakan Actual Request untuk memverifikasi header dan nilai variabel yang benar-benar dikirim.

Otomatiskan dengan Apidog CLI

Parameter global dan environment tidak hanya berlaku di GUI. Konfigurasi yang sama juga digunakan saat menjalankan skenario otomatis melalui Apidog CLI.

Instal CLI dengan Node.js v16+:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Jalankan skenario terhadap environment tertentu:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Penjelasan flag:

  • -t: ID skenario pengujian.
  • -e: ID environment.
  • -r: reporter, misalnya cli, html, atau junit.

Dengan flag -e, CLI memakai variabel environment yang sama, termasuk {{token}}. Jadi header global dan token yang bekerja di GUI juga dapat digunakan dalam CI.

Baca panduan instalasi Apidog CLI untuk setup CLI, serta panduan Apidog CLI di GitHub Actions untuk integrasi pipeline otomatisasi.

FAQ

Apakah parameter global menimpa header pada endpoint tertentu?

Tidak. Parameter global memiliki prioritas lebih rendah. Jika endpoint mendefinisikan Authorization sendiri, nilai pada endpoint tersebut yang digunakan.

Di mana token harus disimpan?

Simpan token pada variabel environment atau global, bukan sebagai teks biasa di Default Value.

Gunakan pola berikut:

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Untuk mengambil token dari respons login dan menggunakannya kembali, lihat panduan ekstraksi variabel dengan JSONPath.

Bagaimana cara memastikan header global terkirim?

Kirim request, lalu buka tab Actual Request. Jika header terlihat di sana, header sudah terkirim.

Bisakah header default diterapkan hanya ke satu folder?

Bisa, menggunakan skrip pra-permintaan folder:

pm.request.headers.add({ key: 'X-Admin-Scope', value: 'full' });
Enter fullscreen mode Exit fullscreen mode

Apakah parameter global dan variabel environment memerlukan paket berbayar?

Dokumentasi fitur ini tidak mencantumkan batasan tingkatan untuk parameter global, variabel environment, atau skrip pra-permintaan tingkat folder.

Ringkasan

Untuk menerapkan header konsisten ke seluruh proyek:

  1. Buat Authorization dan X-Api-Version sebagai parameter global di Manajemen Lingkungan.
  2. Simpan token sebagai variabel {{token}}, bukan nilai teks biasa.
  3. Periksa tab Actual Request untuk memastikan header benar-benar dikirim.
  4. Gunakan skrip pra-permintaan jika header hanya diperlukan pada satu folder.
  5. Gunakan environment yang sama saat menjalankan skenario melalui Apidog CLI.

Untuk mencoba konfigurasi ini di proyek Anda, unduh Apidog dan buat header global pertama Anda.

Top comments (0)