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

Zašto većina API dokumentacije ne uspijeva

Opisuju krajnje točke i preskaču dijelove koji zapravo zaustavljaju ljude: kako se autentificirati, kako izgleda realističan zahtjev, što znači pogreška i što učiniti s njom. Čitatelj tada otvara tiket za podršku, što je trošak koji dokumentacija treba ukloniti.

Kako je pišem

Iz izvora, ne iz sjećanja. Čitam rute, sloj validacije i rukovatelje pogreškama, a zatim sam pozivam API s pravim vjerodajnicama. Svaki primjer u dokumentaciji je zahtjev koji sam napravio i odgovor koji sam primio — nema izmišljenih podataka, nema statusnih kodova koje krajnja točka nikada ne vraća.

Što dokumentacija sadrži

• Autentifikacija: dobivanje tokena, osvježavanje i što se događa kada istekne usred sesije.
• Svaka krajnja točka s parametrima, potpuni primjer zahtjeva i stvarni oblik odgovora.
• Referenca pogrešaka koja mapira svaki kod pogreške na uzrok i rješenje, umjesto da samo ponavlja poruku.
• Put za početak rada koji novog programera vodi od nule do uspješnog poziva za manje od deset minuta.
• Ograničenja brzine, paginacija, web-kuke i idempotencija objašnjeni tamo gdje se zapravo primjenjuju.

Format

Markdown u vašem repozitoriju, strukturiran za OpenAPI ili web-mjesto s dokumentacijom — što god ćete zapravo održavati. Primjeri koda na jezicima o kojima vaši korisnici pitaju, provjereni pokretanjem. Postman ili slična kolekcija uključena ako je želite.

Što mi treba

Pristup repozitoriju ili OpenAPI datoteka, jedna radna vjerodajnica za testno okruženje i sva pitanja na koja je vaš tim za podršku umoran od odgovaranja. Ta pitanja su nacrt.

Nije uključeno

Marketinški tekst. Ovo precizno dokumentira što softver radi; odredišna stranica je drugačiji zanat.

Vrijeme izrade i komunikacija

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