Panduan Lengkap Parameter API: Dari Path hingga Body Sekaligus

Jika kamu sudah cukup lama membangun API, kemungkinan besar kamu pernah mengalami dialog batin ini berkali-kali:

“Haruskah parameter ini dimasukkan ke dalam path, query string, header, body… atau cookies? Tunggu—apakah aku bahkan butuh cookies?”

Tenang saja—kamu tidak sendirian.

Pertanyaan-pertanyaan ini umum, dan memang penting. API yang terstruktur dengan baik lebih mudah digunakan, diuji, dan dipelihara. Kabar baiknya? Ada logika yang jelas di balik penempatan parameter. Setelah kamu memahami tujuan dari masing-masing jenis, kamu tidak akan ragu lagi.

Panduan ini menjelaskan 5 jenis utama parameter API, memberikan praktik terbaik di dunia nyata, dan menunjukkan bagaimana alat seperti EchoAPI dapat membantu kamu merancang dan mendokumentasikan API seperti seorang profesional.

5 Jenis Utama Parameter API

Dalam API RESTful yang umum, parameter bisa muncul di tempat berbeda tergantung pada perannya dalam permintaan:

1. Path Parameter – Untuk menemukan resource tertentu
2. Query Parameter – Untuk memodifikasi atau memfilter permintaan
3. Header Parameter – Untuk metadata atau konteks
4. Cookie Parameter – Untuk pelacakan sesi atau penyimpanan
5. Body Parameter – Untuk mengirim data kompleks atau terstruktur

Meskipun tampilannya berbeda, semua parameter ini memiliki tujuan yang sama: mengirim input dari client ke server.

Mari kita bahas satu per satu, lengkap dengan contoh, tips penggunaan, dan potongan kode.

1. Path Parameter

GET /users/42

• Nama Parameter: id (meskipun tampil sebagai 42, biasanya route didefinisikan sebagai /users/:id)
• Nilai Parameter: 42
• Lokasi: Bagian dari path URL

// Mengakses dengan Express.js
const userId = req.params.id;

🔹 Ini adalah contoh klasik penggunaan path parameter.
👉 req.params adalah objek untuk mengambil path parameter.
✔️ Dalam kasus ini, userId diambil dari req.params.

2. Query Parameter

GET /users?age=25&sort=desc

• Nama dan Nilai Parameter:
  • age = 25
  • sort = desc
• Lokasi: Setelah tanda ? di URL

const { age, sort } = req.query;

🔹 Ini adalah query parameter, diakses melalui req.query.
✔️ age dan sort tidak ada di req.params, tapi di req.query, cocok untuk filter dinamis dan opsional.

3. Header Parameter

Authorization: Bearer <token>
Content-Type: application/json

• Nama dan Nilai Parameter:
  • Authorization = Bearer <token>
  • Content-Type = application/json
• Lokasi: Di dalam header HTTP

const token = req.headers.authorization;

🔹 Ini bukan bagian dari req.params, tapi tetap merupakan parameter permintaan yang valid.
✔️ Gunakan req.headers untuk mengakses nilai seperti token autentikasi dan tipe konten.

4. Cookie Parameter

Cookie: session_id=xyz123

• Nama dan Nilai Parameter:
  • session_id = xyz123
• Lokasi: Di dalam field Cookie pada header permintaan HTTP

const sessionId = req.cookies.session_id;

🔹 Seperti header, cookie juga parameter permintaan, tapi bukan bagian dari req.params.
✔️ Cookie biasanya diakses melalui req.cookies, dengan asumsi middleware cookie-parser aktif.

5. Body Parameter

{
  "name": "Alice",
  "email": "alice@example.com"
}

• Nama dan Nilai Parameter:
  • name = Alice
  • email = alice@example.com
• Lokasi: Di dalam body permintaan HTTP

const { name, email } = req.body;

🔹 Body parameter umum digunakan dalam permintaan POST atau PUT untuk mengirim data terstruktur.
✔️ Parameter ini diakses melalui req.body, bukan req.params.

Cara Memilih Jenis Parameter yang Tepat

Dalam pengembangan sehari-hari, penggunaan parameter API dengan benar tidak hanya membuat dokumentasi lebih jelas—tetapi juga meningkatkan efisiensi debugging dan memperlancar kolaborasi antara tim frontend dan backend. Simak tips berikut:

Path Parameter: Untuk "Mengidentifikasi Resource"

Rekomendasi: Jika sebuah nilai secara unik mengidentifikasi resource, masukkan ke dalam path. Tanpa kompromi.

🔹 EchoAPI mendukung pengenalan path RESTful secara otomatis—cukup gunakan {id} langsung.

Query Parameter: Untuk "Mengontrol Perilaku"

Rekomendasi: Untuk filter, paginasi, atau pencarian, gunakan query parameter.

🔹 Di EchoAPI, kamu bisa mengatur query parameter secara visual. Lengkapi contoh nilai, tambahkan deskripsi, bahkan atur sebagai parameter global untuk digunakan ulang.

Header Parameter: Untuk "Mengirim Konteks"

Rekomendasi: Token, preferensi bahasa, penanda format, dll. harus berada di header, bukan di URL.

🔹 EchoAPI memungkinkan pengaturan header umum lewat dropdown—tidak perlu ketik ulang setiap kali.

Body Parameter: Untuk "Mengirim Isi Utama"

Rekomendasi: Saat mengirim data terstruktur, formulir, atau file, gunakan body permintaan.

🔹 EchoAPI mendukung berbagai format body: JSON, form-data, urlencoded, raw, binary, msgpack, XML, dan lainnya. Kamu juga bisa mengaitkan dengan Schema untuk membuat contoh struktur secara otomatis.

Cookie Parameter: Kuno Tapi Masih Relevan

Rekomendasi: Umumnya untuk sesi atau pelacakan. Dalam arsitektur frontend-backend terpisah, sebaiknya hindari. Untuk API publik, gunakan token.

🔹 EchoAPI mendukung pengaturan cookie opsional, sangat membantu untuk simulasi atau replikasi perilaku browser saat pengujian.

Jenis parameter berbeda punya tempat berbeda, tapi semuanya adalah bahasa komunikasi antara klien dan API. Tempatkan dengan tepat, dan API-mu akan “berbicara” dengan jelas.

Kalau artikel ini membantumu memahami penempatan parameter, bagikan ke timmu.
Tidak ada lagi yang bertanya: “ID ini harus masuk path atau query?”

Mulai sekarang, API kita berlogika dan terstruktur.

EchoAPI: Pengalaman Desain API yang Ramping

Desain bukan hanya dokumentasi—itu cetak biru. Desain membuat API lebih mudah untuk kolaborasi, digunakan ulang, dan diuji.

• Tampilan desain memungkinkan kamu mendefinisikan status, tag, parameter, dan struktur respons, serta membuat mock contoh dan respons ekspektasi cerdas dari schema.
• Setelah struktur permintaan didefinisikan, EchoAPI otomatis menghasilkan endpoint debug dan layanan mock. Tim frontend dan QA bisa langsung mulai integrasi, tanpa harus menunggu backend siap.
• Mendukung berbagai metode autentikasi: Bearer, Basic, OAuth1, AWS, NTLM—bahkan Akamai EdgeGrid.

Referensi Cepat untuk Diri Sendiri Saat Mendesain API

Dan satu hal terakhir:

EchoAPI menangani seluruh alur kerja—dari desain hingga dokumentasi, debugging hingga mock testing. Dilengkapi AI untuk bantu generate struktur antarmuka, bisa dicoba gratis, dan integrasi mudah dengan berbagai lingkungan pengembangan.

Tulis kode lebih sedikit, fokus pada logika bisnis yang lebih penting.