Dokumentácia k API
- Viktoria Sunderlikova
- marketa.simoni
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.
Prístupové Url na dokumentáciu sú definované v metadátach API. (DCAT štandard)
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://spec.openapis.org/oas/latest.html
https://blog.hubspot.com/website/api-documentation
https://golemioapi.docs.apiary.io/#introduction/description