Napisaću jasnu API dokumentaciju koju vaši programeri mogu pratiti od prvog dana

Zašto većina API dokumentacije ne uspeva

Oni opisuju krajnje tačke i preskaču delove koji zapravo zaustavljaju ljude: kako se autentifikovati, kako izgleda realističan zahtev, šta znači greška i šta učiniti povodom toga. Čitalac tada otvara tiket za podršku, što je trošak koji dokumentacija treba da eliminiše.

Kako je pišem

Iz izvora, ne iz sećanja. Čitam rute, sloj validacije i rukovaoce greškama, a zatim sam pozivam API sa stvarnim akreditivima. Svaki primer u dokumentaciji je zahtev koji sam napravio i odgovor koji sam primio — nema izmišljenih podataka, nema statusnih kodova koje krajnja tačka nikada ne vraća.

Šta dokumentacija sadrži

• Autentifikacija: dobijanje tokena, osvežavanje i šta se dešava kada istekne usred sesije.
• Svaka krajnja tačka sa parametrima, kompletan primer zahteva i stvarni oblik odgovora.
• Referenca grešaka koja mapira svaki kod greške na uzrok i rešenje, umesto da samo ponavlja poruku.
• Put za početak rada koji novog programera vodi od nule do uspešnog poziva za manje od deset minuta.
• Ograničenja brzine, paginacija, veb-kukovi i idempotencija objašnjeni tamo gde se zapravo primenjuju.

Format

Markdown u vašem repozitorijumu, strukturiran za OpenAPI ili sajt sa dokumentacijom — šta god ćete zapravo održavati. Uzorci koda na jezicima za koje vaši korisnici pitaju, verifikovani pokretanjem. Postman ili slična kolekcija uključena ako želite.

Šta mi je potrebno

Pristup repozitorijumu ili OpenAPI datoteka, jedan radni akreditiv za testno okruženje i sva pitanja na koja je vaš tim za podršku umoran od odgovaranja. Ta pitanja su osnova.

Nije uključeno

Marketinški tekst. Ovo dokumentuje šta softver radi, precizno; odredišna stranica je drugačija veština.

Vreme izrade i komunikacija

Prvi kompletan nacrt obično stiže u roku od nedelju dana, a vi ga pregledate u odnosu na pitanja na koja vaš tim za podršku stalno odgovara. Radije bih da me rano ispravi inženjer koji poznaje granične slučajeve nego da isporučim nešto uglađeno i pogrešno. Svaki primer u konačnom dokumentu je izvršen u odnosu na vaš API, tako da ništa u njemu nije aspirativno.