Belajar Curl - JSON & REST API Testing

#Pendahuluan

Di episode 5 sebelumnya kalian sudah bermain dengan POST, PUT, DELETE, dan form data — cara mengirimkan data ke server lewat badan request (request body). Sekarang saatnya naik satu level: data yang paling sering dikirim dan diterima oleh API modern adalah JSON. Hampir semua REST API produksi berbicara dalam JSON, dari autentikasi sampai CRUD resource. Episode ini akan membekali kalian dengan teknik mengirim JSON yang benar, membaca responsnya secara efisien, dan membangun workflow testing yang bisa diulang dengan hasil konsisten.

Kenapa JSON begitu penting? Karena JSON adalah lingua franca pertukaran data antar service — ringan, bisa dibaca manusia, dan didukung native oleh hampir semua bahasa pemrograman. Kalau kalian menguasai kombinasi curl + JSON + jq, kalian sudah punya "swiss army knife" untuk menguji API apa pun tanpa perlu menyalakan Postman dulu.

#Mengirim Body JSON dengan Content-Type

#Mengapa Header Content-Type Diperlukan

Saat mengirim body, server perlu tahu format body tersebut supaya bisa mem-parsing-nya dengan benar. Header Content-Type adalah label yang memberi tahu server: "body ini bertipe JSON". Tanpa label itu, banyak framework web akan menolak atau salah menafsirkan body — hasilnya error 415 Unsupported Media Type atau data yang tidak terbaca sama sekali.

kirim-json-manual.sh

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Budi", "email": "budi@example.com"}'

Perhatikan dua bagian penting di atas: -H "Content-Type: application/json" sebagai label format, dan -d '{"name": "Budi"}' sebagai payload JSON-nya. Kombinasi inilah yang paling umum dijumpai di dokumentasi API dan di script CI/CD kalian.

Ada satu detail yang sering menjebak pemula: -X POST sebenarnya tidak wajib. Saat curl mendeteksi -d, ia otomatis mengirim request POST — tetapi sekaligus menambahkan header Content-Type: application/x-www-form-urlencoded. Karena itu kalian wajib meng-override header tersebut menjadi application/json, agar server membaca body sebagai JSON, bukan sebagai form biasa.

#Shorthand `--json`

Menulis dua atau tiga flag secara berulang-ulang itu membosankan dan rawan salah ketik. Sejak curl 7.82.0, ada shorthand yang mempersingkat semuanya: --json. Satu flag ini melakukan tiga hal sekaligus — mengirim request POST, mengatur Content-Type: application/json, dan menyematkan payload-nya.

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Budi", "email": "budi@example.com"}'

Kedua perintah menghasilkan request yang identik. --json juga menerima banyak bentuk input: string literal, path file dengan awalan @, maupun data dari stdin. Untuk payload yang kompleks atau panjang, simpan JSON di file lalu kirim dengan --json @payload.json — jauh lebih mudah dipelihara daripada menulis ratusan karakter di satu baris terminal.

Tip

Awalan @ pada -d dan --json berarti "baca isi file", bukan mengirim literal. Jadi --json @payload.json membaca isi file payload.json sebagai body, sedangkan --json '{"name":"Budi"}' mengirim string literal. Bedanya hanya terletak pada awalan @ — dan ini berlaku untuk semua opsi transfer data di curl.

#Mengolah Respons JSON dengan jq

Respons API modern biasanya berupa JSON yang panjang, bersarang, dan sulit dibaca saat ditampilkan mentah. Di sinilah jq masuk — utilitas baris perintah untuk memformat, menyaring, dan mengubah JSON. Kombinasi curl + jq adalah salah satu pipeline paling produktif yang bisa kalian pelajari di shell.

format-json.sh

curl -s https://api.example.com/users | jq

Tanpa jq, respons panjang tampil menggulung tanpa struktur. Dengan jq, JSON di-pretty-print — indentasi rapi dan mudah dipindai mata. Pipeline ini bekerja karena curl -s mencetak body respons ke stdout, lalu jq membaca stdin dan menampilkan versi yang sudah diformat.

Untuk menyaring data, jq memakai filter berbasis path:

filter-json.sh

curl -s https://api.example.com/users | jq '.[] | {name, email}'

Filter .[] mengambil setiap elemen dari array, dan {name, email} memilih hanya field name dan email. Kalian bisa merantai filter lebih jauh: select(.role == "admin") untuk memilih hanya user admin, atau .length untuk menghitung jumlah elemen. Semakin rumit respons, semakin besar nilai jq.

#Workflow CRUD Lengkap

Sekarang mari kita rangkai semuanya menjadi workflow testing REST yang utuh terhadap satu resource — misalnya /users di API development kalian.

read-get.sh

curl -s https://api.example.com/users | jq '.[] | {id, name}'

create-post.sh

curl -s --json '{"name": "Sari", "email": "sari@example.com"}' \
  https://api.example.com/users

update-put.sh

curl -s -X PUT https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{"name": "Sari Utami", "email": "sari@example.com"}'

delete-delete.sh

curl -s -X DELETE https://api.example.com/users/42

Perhatikan pola di atas: setiap operasi mewakili satu kata kerja HTTP (verb) dan satu resource. GET untuk membaca, POST untuk membuat, PUT untuk memperbarui, DELETE untuk menghapus. Struktur URL yang identik (/users/42) dengan verb berbeda adalah esensi arsitektur REST — dan curl menjadi alat yang pas karena ia bisa memanggil verb apa pun dengan bebas.

#Memeriksa Status Code

Melihat body respons saja tidak cukup untuk memastikan request sukses. Kode status HTTP adalah sumber kebenaran: 200 berarti OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 404 Not Found, dan 500 Server Error. curl punya fitur -w (write-out) untuk mencetak informasi tambahan — termasuk status code — setelah transfer selesai.

check-status.sh

curl -s -o /dev/null -w "%{http_code}\n" https://api.example.com/users/42

Kombinasi -o /dev/null membuang body agar tidak membanjiri terminal, lalu -w "%{http_code}" mencetak hanya angka statusnya. Ini teknik yang sangat umum di script monitoring dan CI: cek apakah endpoint mengembalikan 200, dan jika tidak, tandai sebagai gagal.

Tip

Untuk membaca respons sekaligus status, gabungkan keduanya: curl -s -w "\nHTTP %{http_code}\n" URL. Baris HTTP 200 tercetak di bagian bawah output, sehingga kalian tetap melihat body sekaligus statusnya dalam satu jendela — nyaman untuk debugging cepat.

#Best Practice Request yang Reproducible

Sebuah request dikatakan reproducible jika bisa dijalankan ulang kapan pun dengan hasil yang dapat diprediksi. Ini kunci untuk testing yang andal di tim. Beberapa kebiasaan yang perlu dibangun:

Simpan payload di file, bukan di memori. Gunakan --json @payload.json untuk payload besar agar mudah direview dan diubah.
Eksplisit terhadap method. Jangan bergantung pada default; tulis -X DELETE atau --json secara eksplisit sesuai niat.
Verifikasi status code, bukan sekadar tidak ada error. Gunakan -w "%{http_code}" di script untuk membuat asersi.
Buang output yang tidak perlu. -s (silent) menekan progress meter; -o /dev/null membuang body saat yang dicari hanya status.

reproducible-request.sh

URL="https://api.example.com/users"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
  --json @payload.json "$URL")
echo "create status: $STATUS"

#Penutup

Pada episode 6 ini kalian telah melengkapi kemampuan REST testing: mengirim body JSON dengan -H "Content-Type: application/json" dan -d '{"key":"value"}', menyederhanakannya dengan shorthand --json, mengolah respons JSON lewat pipeline jq, menjalankan workflow CRUD lengkap, serta memeriksa status code dengan -w "%{http_code}" untuk request yang reproducible.

Yang paling penting untuk dibawa pulang: kombinasi curl + jq adalah kekuatan super — dari request mentah langsung menjadi data terstruktur yang siap dipakai script. Semakin sering kalian membangun workflow di atas, semakin cepat dan andal proses testing API kalian.

Di episode 7 selanjutnya kita akan berpindah dari bermain data ke bermain file — bagaimana mengunduh file dengan nama yang benar, melanjutkan download yang terputus, mengunggah file ke server, dan mengakses FTP maupun SFTP. Sampai jumpa!