Dokumentácia k API je v podstate návod na použitie, ktorý vysvetľuje ako používať API a jeho služby. Táto príručka môže obsahovať návody, príklady kódu, snímky obrazovky a čokoľvek iné, čo používateľom pomôže lepšie pochopiť, ako pracovať s rozhraním API.
Dobrá dokumentácia API popisuje jeho koncové body, vysvetľuje prečo by ste ich mali používať, a ponúka veľmi konkrétne príklady využitia – a to všetko spôsobom, ktorý je dostupný pre začiatočníkov aj pokročilejších používateľov. Zlá dokumentácia API je príliš technická a textová, a preto nie je zrozumiteľná pre všetkých používateľoch.
Pri písaní API dokumentácie by sme preto mali brať do úvahy kto je naša cieľová skupina, kto s ňou bude pracovať, ako sa bude využívať.
Používateľov je možné rozdeliť do 2 skupín. Prvou skupinou sú používatelia, ktorí chcú aktívne využívať API preto hľadajú príručky, príklady kódu. Ďalšou skupinou sú používatelia, ktorých zaujímajú ceny, obmedzenia, bezpečnosť. Sú to napr. produktoví manažéri.
Dokumentácia k API by mala preto obsahovať:
1, možnosti autentifikácie (ako získať API kľúč, ako používať OAuth 2.0)
2, obmedzenia (obmedzenia sa týkajú napr. koľkokrát je možné zaslať API požiadavku v danom časovom období
3, podmienky použitia ( právne podmienky a obmedzenia používanie API)
4, zoznam zmien v API (používatelia si následne vedia upraviť svoje aplikácie)
5, príklady kódu a možnosti jeho využitia
6, zoznam statusov a chybových hlášok (chybové hlášky by mali obsahovať aj ich popis)
7, zrozumiteľnosť (dokumentácia by mala byť zrozumiteľná aj pre začiatočníkov)
8, aktuálnosť dokumentácie
Užitočné linky:
https://blog.hubspot.com/website/api-documentation
https://golemioapi.docs.apiary.io/#introduction/description
0 komentárov