Cara Memperbaiki Dokumentasi API yang Buruk dengan EchoAPI

⚠️ PERINGATAN: Ini adalah panduan “Cara Menghancurkan Dokumentasi API Anda dan Merusak Kewarasan Tim Anda”.
Jika Anda benar-benar menginginkan dokumentasi API yang mudah dibaca dan dipelihara, JANGAN ikuti langkah-langkah ini!

Mari kita jujur: dokumentasi API sering kali menjadi bagian terburuk dari pengembangan perangkat lunak. Semua orang membutuhkannya, tidak ada yang ingin menulisnya, dan entah bagaimana selalu berakhir menjadi sumber frustrasi. Ingin tahu cara membuat mimpi buruk ini lebih parah lagi? Cukup ikuti langkah-langkah sederhana di bawah ini dan saksikan tim developer Anda hancur lebur.

Langkah 1: Tolak Semua Standar — Gunakan “Word + Excel” Seperti Tahun 1999

Siapa butuh skema JSON yang terstruktur atau file Swagger kalau Anda bisa punya… kolase kacau tangkapan layar Excel yang ditempel ke dokumen Word?

Inilah mahakarya yang pernah saya temui:

• Parameter antarmuka dibuang dalam baris Excel tanpa penjelasan
• Nama parameter salah di mana-mana
• Tidak ada versi atau catatan perubahan
• Dokumentasi otomatis? Hahaha, tentu tidak

Hasilnya? Developer front-end menatap tangkapan layar buram sambil mencoba memecahkan mantra ajaib agar API bisa bekerja. Spoiler: Tidak berhasil.

“Tipe field ini apa?” — “Lihat aja screenshot, bro.”
“Tapi beda dari versi sebelumnya!” — “Mungkin itu screenshot yang beda.”
Developer front-end: menarik rambut
QA tester: menangis pelan

Langkah 2: GET Adalah Raja — Gunakan GET untuk Segalanya, Termasuk Mutasi

Lupakan prinsip RESTful. Siapa peduli kalau GET artinya “mengambil data”? Masukkan semua operasi create, update, dan delete ke dalam permintaan GET. Semakin Anda melakukannya, semakin bingung semua orang.

Contoh:

GET /updateUserName
Content-Type: application/json

{
  "userId": "123",
  "newName": "Jane Doe"
}

Kenapa ini buruk? Karena:

• Browser dan proxy meng-cache respons GET dengan asumsi tidak ada efek samping
• GET biasanya tidak punya body, jadi banyak klien tidak mengirim payload dengan benar
• Front-end tidak bisa membedakan apakah ini “membaca” atau “menulis” data

Sorotan sesi debugging:

“Kenapa data nggak update?” — “Karena browser nyimpen cache GET-nya, bodoh!”
“Kenapa di log nggak ada POST?” — “Karena kita gak pernah pakai POST.”
“Bisa percaya header cache-nya?” — “Percaya? Apa itu?”

Langkah 3: Penamaan Endpoint Seperti Teka-Teki Indiana Jones

Konvensi penamaan? Konsistensi? Lupakan.

Contoh dari proyek klien:

• /getUserList
• /userlist
• /allUsers
• /fetch_users
• /getUsreList (typo legendaris!)

Semua orang menebak-nebak mana yang benar — atau apakah semuanya salah.

Obrolan biasa:

Alice: “Aku pakai /getUserList tapi hasilnya array kosong.”
Bob: “Coba /allUsers, itu berhasil di aku.”
Alice: “Dokumennya bilang /userlist. Kamu yakin lihat versi yang benar?”
Bob: “Kita bahkan gak tahu versi yang mana yang benar.”

Langkah 4: Masukkan Semua Parameter ke Dalam Request Body dan Lupakan Query String atau Path

Mau melakukan pagination tiket? Hebat! Kirim semua parameter pagination dan filter ke dalam body POST, bahkan kalau itu sebenarnya operasi GET.

POST /getTickets
Content-Type: application/json

{
  "page": 1,
  "pageSize": 50,
  "status": "open"
}

Kenapa ini menyedihkan?

• Tidak bisa uji pagination lewat URL di browser — harus bikin JSON body setiap kali
• Proxy cache tidak bisa cache apa pun dari URL
• Log server jadi gelap — tidak ada query parameter untuk ditelusuri

Langkah 5: Selalu Kembalikan HTTP 200 OK, Bahkan untuk Error — Sembunyikan Gagalnya di Dalam Body

Siapa butuh kode status HTTP? Selalu kembalikan 200 dan masukkan informasi error dalam payload JSON.

{
  "code": 400,
  "message": "Parameter tidak valid"
}

Sekarang developer front-end harus bikin logika tambahan:

fetch(url)
  .then(res => res.json())
  .then(data => {
    if (data.code !== 200) {
      alert(`Oops: ${data.message}`);
    }
  });

Kenapa ini buruk?

• Gateway API, alat monitoring, dan klien HTTP mengandalkan kode status HTTP
• Debugging dan otomatisasi jadi mimpi buruk
• Semua konsumen harus buat error handling kustom

Langkah 6: Format Respons Acak — JSON, CSV, XML, Semua Campur!

Kenapa pilih satu format kalau bisa membingungkan semua orang dengan banyak format?

• Beberapa endpoint mengembalikan JSON
• Yang lain mengeluarkan file CSV dengan format aneh
• Dan ada yang masih pakai XML demi nostalgia

Contoh:

GET /users.csv
HTTP/1.1 200 OK
Content-Type: text/csv

id,name,salary
1,John,$3000
2,Jane,$2800

Front-end sekarang harus:

• Menulis parser terpisah untuk tiap format
• Menghapus simbol mata uang sebelum parsing angka
• Menangani tipe field yang tidak konsisten

Cara Menulis Dokumentasi API yang Buruk — Ringkasan Cepat

• Tidak menulis dokumentasi atau menulis yang buruk dan tidak pernah diperbarui
• Menyalahgunakan HTTP verb, terutama GET
• Mengacaukan penamaan endpoint
• Masukkan semua parameter ke dalam body, bukan URL
• Selalu kembalikan HTTP 200, sembunyikan error di body
• Gunakan berbagai format respons dalam satu API

Selamat, Anda telah menciptakan pengalaman API yang beracun!

Capek Dengan Semua Ini? Kenalan dengan EchoAPI — Penyelamat Dokumentasi API 🛠️

Menulis dokumentasi API yang baik memang menyakitkan. Semua tahu dibutuhkan, tapi:

• Front-end: “Aku nggak bisa mulai tanpa dokumentasi!”
• Back-end: “Aku sibuk, dokumentasi nanti aja.”
• QA: “Mana kode error-nya? Field mana yang wajib?”

Semua jadi korban.

EchoAPI mengubah permainan dengan membuat dokumentasi API:

• Visual dan interaktif
• Otomatis diperbarui
• Bisa diuji dan dimock
• Kolaboratif antar tim

Apa Itu EchoAPI?

Sebuah platform siklus hidup API lengkap untuk tim dev:

Desain → Dokumentasi → Mock → Uji → Kolaborasi

Dengan kata lain: dokumentasi API yang tidak payah dan benar-benar membantu tim Anda lebih cepat rilis.

Skenario 1: Dokumentasi Usang dan Parameter Kacau?

Sebelumnya: Dokumen Word dan screenshot berserakan di Slack.

Dengan EchoAPI:

✅ Antarmuka drag-and-drop visual untuk header, query, path, body
✅ Tipe data, field wajib, contoh nilai, dan deskripsi yang bisa diatur
✅ Dokumentasi selalu diperbarui otomatis

Skenario 2: Front-end Menunggu Back-end?

Sebelumnya: Front-end cuma bisa duduk menunggu.

Dengan EchoAPI:

✅ Mock server 1-klik dari skema dan contoh
✅ Front-end bisa mulai integrasi meski back-end belum selesai
✅ Pengembangan paralel jadi mungkin

Skenario 3: Error Response Membingungkan?

Sebelumnya: Tidak ada dokumentasi error, format tidak konsisten.

Dengan EchoAPI:

✅ Definisikan banyak skenario respons (200, 400, 401, 500) dengan contoh
✅ Desain JSON schema secara visual dengan data mock otomatis
✅ Ekspor kasus uji untuk otomatisasi QA

Skenario 4: Autentikasi dan Upload Rumit?

Sebelumnya: Tidak jelas soal token, multipart upload, atau content-type.

Dengan EchoAPI:

✅ Dukungan built-in untuk OAuth, Bearer token, Basic Auth, AWS Signing
✅ Tangani JSON, form-data, binary — semua terdokumentasi dan bisa diuji
✅ Tidak ada lagi tebakan “gimana cara upload file ini?”

Skenario 5: Parameter Panjang dan Skema Kompleks?

Sebelumnya: Mengetik manual dengan typo dan field yang kurang.

Dengan EchoAPI:

✅ Template parameter yang bisa digunakan ulang
✅ Field bersama antar API (seperti token, versi, bahasa)
✅ Dukungan Markdown untuk gambar dan tabel
✅ Kolaborasi dengan kontrol versi dan perizinan

Fitur Bonus

• Ekspor ke HTML, PDF, Markdown, OpenAPI (Swagger)
• Pengujian API online dengan riwayat dan log
• Sematkan dokumentasi ke portal atau wiki perusahaan
• Integrasi CI/CD untuk notifikasi perubahan otomatis

Kenapa EchoAPI Luar Biasa

Berhenti buang waktu menulis dokumentasi API yang buruk.
Mulailah gunakan EchoAPI untuk membuat API Anda jelas, andal, dan mudah digunakan.

Tidak ada lagi:

• “Gimana cara panggil API ini?”
• “Field mana yang wajib?”
• “Kode error-nya apa aja?”

Karena semuanya sudah tertulis jelas di dokumentasinya.