API je tako dober, kot je dobra njegova dokumentacija, zato poskrbite, da bo vaš odkrit z visokokakovostnimi navodili in drugimi pomembnimi podrobnostmi.

Več organizacij izkorišča moč API-jev za optimizacijo svojega poslovanja. API-ji so postali način za odklepanje vrednosti in zagotavljanje dodatne storitve.

Kljub njihovi splošni priljubljenosti ni vsak API uspešen. Sprejetje in uporaba API-ja v veliki meri določata njegov uspeh. Če želite povečati sprejemanje, mora biti vaš API enostaven za iskanje in uporabo.

Najboljši način za to je, da podrobno dokumentirate svoj API. To vključuje podrobnosti kritičnih komponent za lažje razumevanje. Poiščite nekaj komponent, ki bi jih morali vključiti v svojo dokumentacijo API-ja.

Kaj je dokumentacija API?

Dokumentacija API je tehnična vsebina, ki podrobno opisuje API. To je priročnik, ki vsebuje vse informacije, potrebne za delo z API-jem. Dokument zajema življenjski cikel API-ja in navodila za integracijo in uporabo njegovih komponent.

Dokumentacija API-ja zajema opise virov, končne točke, metode, zahteve in primere odgovorov. Vključuje lahko tudi praktične vodnike in vadnice, ki uporabnikom pokažejo, kako ga integrirati. Raziskovanje vsakega razdelka daje uporabnikom dobro razumevanje integracije in uporabe API-ja.

Urejevalniki, kot je Google Dokumenti, so se nekoč pogosto uporabljali za profesionalno dokumentacijo API-jev. Dandanes obstajajo naprednejša orodja, kot so Document 360, Confluence in GitHub Pages. Ta orodja pomagajo integrirati besedilo in kodo za lažje poteke dela.

1. Pregled in namen API-ja

Prvi korak pri dokumentiranju API-ja je obveščanje uporabnikov, za kaj gre. Vključite informacije o vrsti virov, ki jih ponuja. API-ji imajo običajno različne vire, ki jih vrnejo, tako da lahko uporabnik zahteva, kar potrebuje.

Opis je kratek, običajno en do trije stavki, ki opisujejo vir. Opišite razpoložljive vire, končne točke in metode, povezane z vsako končno točko. Kot razvijalec API-ja najbolje opišete njegove komponente, funkcionalnost in primer uporabe.

Tukaj je primer opisa API-ja Airbnb:

2. Metode avtentikacije in avtorizacije

API-ji obravnavajo na tisoče zahtev in ogromne količine podatkov. Avtentikacija je eden od načinov, kako zagotoviti, da so podatki vašega API-ja in uporabnikov varni pred hekerji. API Authentication preveri identiteto uporabnika in jim omogoča dostop do virov.

Obstaja več načinov za zagotovitev varnost končne točke. Večina API-jev uporablja ključ API-ja. To je niz znakov, ki jih lahko uporabnik ustvari s spletne strani in uporabi za preverjanje pristnosti.

Dokumentacija API-ja bi morala voditi uporabnike o tem, kako preveriti pristnost in avtorizirati svojo identiteto. Naslednji diagram prikazuje informacije o preverjanju pristnosti API-ja za Twitter.

3. Končne točke, vzorci URI in metode HTTP

V tem razdelku pokažite, kako dostopati do vira. Končne točke prikazujejo samo konec poti, od tod tudi njihovo ime. Prikazujejo dostop do vira in metode HTTP s katero končna točka komunicira, in sicer GET, POST ali DELETE.

En vir ima verjetno različne končne točke. Vsak z drugačno potjo in metodo. Končne točke imajo običajno kratke opise svojega namena in vzorec URL-ja.

Naslednji vzorec kode prikazuje uporabniško končno točko GET na Instagramu.

Dobi me? fields={polja}&access_token={žeton za dostop}

4. Formati zahtev in odgovorov

Formate zahtev in odgovorov morate dokumentirati, da bo uporabnik vedel, kaj lahko pričakuje. Zahteva je URL od odjemalca, ki zahteva vir, medtem ko je odgovor povratna informacija s strežnika.

Sledi vzorčna zahteva, ki jo lahko pošljete API-ju LinkedIn.

DOBITI https://api.linkedin.com/v2/{service}/1234

In tukaj je vzorec odgovora, ki ga lahko vrne:

{
 "id": 1234,
 "relatedEntity": "urn: li: relatedEntity: 6789"
}

5. Parametri in glave

Prav tako morate dokumentirati parametre svojih končnih točk, ki so možnosti, ki jim jih lahko posredujete. Parametri so lahko ID ali številka, ki določa količino ali vrsto podatkov, vrnjenih kot odgovor.

Obstajajo različne vrste parametrov, vključno s parametri glave, poti in poizvedbenega niza. Končne točke lahko vsebujejo različne vrste parametrov.

Nekatere parametre lahko vključite kot glave zahtev HTTP. Običajno so ti za namene preverjanja pristnosti kot ključ API. Tukaj je primer glave s ključi API:

glave: {
 'X-RapidAPI-Key': 'fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635',
 'X-RapidAPI-Host': 'wft-geo-db.p.rapidapi.com'
}

Parametre poti vključite v telo končne točke neposredno na URL-ju. Uporabniku pokažejo, kako in kam naj postavi parametre in kako bo prikazan odziv. Besede v zavitih oklepajih so parametri.

Za predstavitev parametrov poti lahko uporabite tudi dvopičja ali drugo sintakso.

/service/myresource/user/{user}/bicycles/{bicycleId}

Pri poizvedbenih parametrih morate pred poizvedbo na končni točki postaviti vprašaj (?). Vsak parameter za tem ločite z znakom & (&). Microsoft ima dobro dokumentacijo o Graph API.

6. Kode napak in obravnavanje napak

Včasih zahteve HTTP ne uspejo, kar lahko uporabnika zmede. V dokumentacijo vključite pričakovane kode napak, da bodo uporabniki lažje razumeli napake.

LinkedIn ponuja standardne kode napak HTTP za obravnavo napak:

7. Vzorci izrezkov kode

Delčki kode so bistveni deli vaše dokumentacije. Uporabnikom pokažejo, kako integrirati API v različnih jezikih in formatih. V dokumentacijo vključite, kako namestiti in integrirati SDK (komplete za razvoj programske opreme) v različnih jezikih.

RapidAPI ima dobre primere izrezkov kode za razvijalce:

9. Različice API-ja in dnevniki sprememb

Različice API-ja so bistveni del API design. Zagotavlja nemoteno zagotavljanje storitev vašim uporabnikom. Različice lahko izboljšajo API z novimi različicami, ne da bi to vplivalo na odjemalske aplikacije.

Uporabniki lahko še naprej uporabljajo starejše različice ali pa se pravočasno preselijo na naprednejše. Če so v dnevnikih nove spremembe, jih vključite v dokumentacijo, da bodo uporabniki seznanjeni.

Microsoft Graph API ima dobro dokumentirane dnevnike sprememb:

Na koncu vključite pomembne kontakte v dokumentacijo za podporo in povratne informacije. Ti zagotavljajo, da lahko uporabniki pridejo do vas s poročili o napakah in informacijami o tem, kako izboljšati API.

Vrednost API dokumentacije

Če zgradite API za komercialno vrednost, poraba določa njegov uspeh. Da bi uporabniki uporabljali vaš API, ga morajo razumeti.

Dokumentacija oživlja API. Komponente podrobno razlaga v preprostem jeziku, ki uporabnikom prodaja svojo vrednost in uporabo. Uporabniki bodo z veseljem uporabljali vaš API, če bodo imeli odlično izkušnjo razvijalca.

Dobra dokumentacija prav tako pomaga poenostaviti vzdrževanje in skaliranje API-ja. Ekipe, ki delajo z API-jem, lahko za upravljanje uporabljajo dokumentacijo.