Saya Akan Menulis Dokumentasi API yang Jelas yang Dapat Diikuti Pengembang Anda Sejak Hari Pertama

Mengapa sebagian besar dokumen API gagal

Mereka menjelaskan titik akhir dan melewatkan bagian-bagian yang sebenarnya menghentikan orang: cara mengautentikasi, seperti apa permintaan yang realistis, apa arti kesalahan, dan apa yang harus dilakukan. Pembaca kemudian membuka tiket dukungan, yang merupakan biaya yang seharusnya dihilangkan oleh dokumentasi.

Bagaimana saya menuliskannya

Dari sumber, bukan dari ingatan. Saya membaca rute, lapisan validasi, dan penangan kesalahan, lalu memanggil API sendiri dengan kredensial nyata. Setiap contoh dalam dokumentasi adalah permintaan yang saya buat dan respons yang saya terima — tidak ada payload yang dibuat-buat, tidak ada kode status yang tidak pernah dikembalikan oleh titik akhir.

Apa yang terkandung dalam dokumentasi

• Autentikasi: mendapatkan token, menyegarkannya, dan apa yang terjadi ketika token kedaluwarsa di tengah sesi.
• Setiap titik akhir dengan parameter, contoh permintaan lengkap, dan bentuk respons yang sebenarnya.
• Referensi kesalahan yang memetakan setiap kode kesalahan ke penyebab dan perbaikan, daripada hanya mengulang pesan.
• Jalur memulai yang membawa pengembang baru dari nol ke panggilan yang berhasil dalam waktu kurang dari sepuluh menit.
• Batas laju, paginasi, webhook, dan idempotensi dijelaskan di mana mereka benar-benar berlaku.

Format

Markdown di repositori Anda, terstruktur untuk OpenAPI atau situs dokumen — mana pun yang benar-benar akan Anda pertahankan. Contoh kode dalam bahasa yang ditanyakan pengguna Anda, diverifikasi dengan menjalankannya. Koleksi Postman atau yang serupa disertakan jika Anda menginginkannya.

Apa yang saya butuhkan

Akses repositori atau file OpenAPI, satu kredensial kerja untuk lingkungan pengujian, dan pertanyaan apa pun yang tim dukungan Anda lelah menjawabnya. Pertanyaan-pertanyaan itu adalah garis besarnya.

Tidak termasuk

Salinan pemasaran. Ini mendokumentasikan apa yang dilakukan perangkat lunak, secara tepat; halaman arahan adalah kerajinan yang berbeda.

Waktu penyelesaian dan komunikasi

Draf lengkap pertama biasanya tiba dalam seminggu, dan Anda meninjaunya terhadap pertanyaan yang terus dijawab oleh tim dukungan Anda sendiri. Saya lebih suka dikoreksi lebih awal oleh insinyur yang mengetahui kasus-kasus ekstrem daripada memberikan sesuatu yang dipoles dan salah. Setiap contoh dalam dokumen akhir telah dieksekusi terhadap API Anda, jadi tidak ada yang bersifat aspiratif.