Saya Akan Menulis Dokumentasi API yang Jelas yang Boleh Diikuti oleh Pembangun Anda dari Hari Pertama

Mengapa kebanyakan dokumen API gagal

Mereka menerangkan titik akhir dan melangkau bahagian yang sebenarnya menghalang orang: cara mengesahkan, bagaimana rupa permintaan yang realistik, apa maksud ralat, dan apa yang perlu dilakukan mengenainya. Pembaca kemudian membuka tiket sokongan, yang merupakan kos yang wujud untuk dihapuskan oleh dokumentasi.

Bagaimana saya menulisnya

Dari sumber, bukan dari ingatan. Saya membaca laluan, lapisan pengesahan dan pengendali ralat, kemudian memanggil API sendiri dengan kelayakan sebenar. Setiap contoh dalam dokumentasi adalah permintaan yang saya buat dan respons yang saya terima — tiada muatan yang direka, tiada kod status yang tidak pernah dikembalikan oleh titik akhir.

Apa yang terkandung dalam dokumentasi

• Pengesahan: mendapatkan token, menyegarkannya, dan apa yang berlaku apabila ia tamat tempoh di tengah sesi.
• Setiap titik akhir dengan parameter, contoh permintaan lengkap, dan bentuk respons sebenar.
• Rujukan ralat yang memetakan setiap kod ralat kepada punca dan pembetulan, bukannya hanya mengulang mesej.
• Laluan permulaan yang membawa pembangun baharu dari sifar kepada panggilan yang berjaya dalam masa kurang sepuluh minit.
• Had kadar, penomboran, webhook dan idempotensi dijelaskan di mana ia sebenarnya terpakai.

Format

Markdown dalam repositori anda, berstruktur untuk OpenAPI atau tapak dokumen — mana-mana yang akan anda selenggara. Contoh kod dalam bahasa yang ditanya oleh pengguna anda, disahkan dengan menjalankannya. Koleksi Postman atau yang serupa disertakan jika anda mahukannya.

Apa yang saya perlukan

Akses repositori atau fail OpenAPI, satu kelayakan berfungsi untuk persekitaran ujian, dan sebarang soalan yang pasukan sokongan anda sudah bosan menjawab. Soalan-soalan itu adalah garis besar.

Tidak termasuk

Salinan pemasaran. Ini mendokumentasikan apa yang dilakukan oleh perisian, dengan tepat; halaman pendaratan adalah kraf yang berbeza.

Pusingan dan komunikasi

Draf lengkap pertama biasanya tiba dalam masa seminggu, dan anda menyemaknya berdasarkan soalan yang terus dijawab oleh pasukan sokongan anda sendiri. Saya lebih suka diperbetulkan awal oleh jurutera yang mengetahui kes-kes pinggir daripada menyampaikan sesuatu yang digilap dan salah. Setiap contoh dalam dokumen akhir telah dilaksanakan terhadap API anda, jadi tiada apa-apa di dalamnya yang bersifat aspirasi.