10 važnih komponenti API dokumentacije

Više organizacija iskorištava snagu API-ja za optimizaciju svog poslovanja. API-ji su postali način za otključavanje vrijednosti i pružanje dodatne usluge.

Unatoč općoj popularnosti, nije svaki API uspješan. Usvajanje i korištenje API-ja uvelike određuju njegov uspjeh. Da biste povećali usvajanje, vaš API mora biti jednostavan za pronalaženje i korištenje.

Najbolji način da to učinite je detaljno dokumentiranje vašeg API-ja. To uključuje detaljiziranje kritičnih komponenti radi lakšeg razumijevanja. Saznajte neke od komponenti koje biste trebali uključiti u svoju API dokumentaciju.

Što je API dokumentacija?

API dokumentacija tehnički je sadržaj koji detaljno opisuje API. To je priručnik koji sadrži sve informacije potrebne za rad s API-jem. Dokument pokriva životni ciklus API-ja i upute o integraciji i korištenju njegovih komponenti.

API dokumentacija pokriva opise resursa, krajnje točke, metode, zahtjeve i primjere odgovora. Također može uključivati ​​praktične vodiče i upute koji korisnicima pokazuju kako ga integrirati. Istraživanje svakog odjeljka daje korisnicima solidno razumijevanje integracije i korištenja API-ja.

Uređivači poput Google dokumenata nekoć su se široko koristili za profesionalnu API dokumentaciju. Danas postoje napredniji alati kao što su Document 360, Confluence i GitHub Pages. Ovi alati pomažu u integraciji teksta i koda radi lakšeg tijeka rada.

1. Pregled i svrha API-ja

Prvi korak u dokumentiranju API-ja je obavještavanje korisnika o čemu se radi. Uključite informacije o vrsti resursa koje pruža. API-ji obično imaju različite resurse koje vraćaju, tako da korisnik može zatražiti ono što mu treba.

Opis je kratak, obično jedna do tri rečenice koje opisuju izvor. Opišite dostupne resurse, krajnje točke i metode pridružene svakoj krajnjoj točki. Kao programer API-ja, najbolje opisujete njegove komponente, funkcionalnost i slučaj upotrebe.

Evo primjera opisa Airbnb API-ja:

2. Metode autentifikacije i autorizacije

API-ji obrađuju tisuće zahtjeva i goleme količine podataka. Autentifikacija je jedan od načina da osigurate da su podaci vašeg API-ja i korisnika sigurni od hakera. API Authentication provjerava identitet korisnika i daje im pristup resursima.

Postoji nekoliko načina da se osigura sigurnost krajnje točke. Većina API-ja koristi API ključ. Ovo je niz znakova koje korisnik može generirati s web stranice i koristiti za provjeru autentičnosti.

Dokumentacija API-ja trebala bi voditi korisnike o tome kako autentificirati i autorizirati svoj identitet. Sljedeći dijagram prikazuje informacije o autentifikaciji Twitter API-ja.

3. Krajnje točke, URI uzorci i HTTP metode

U ovom odjeljku pokažite kako pristupiti resursu. Krajnje točke pokazuju samo kraj staze, otuda i njihov naziv. Oni pokazuju pristup resursu i HTTP metode s krajnjom točkom u interakciji, naime GET, POST ili DELETE.

Jedan resurs vjerojatno ima različite krajnje točke. Svaki s drugačijim putem i metodom. Krajnje točke obično imaju kratke opise svoje svrhe i obrazac URL-a.

Sljedeći primjer koda prikazuje krajnju točku GET korisnika na Instagramu.

Uzmi me? fields={polja}&access_token={access-token}

4. Formati zahtjeva i odgovora

Morate dokumentirati formate zahtjeva i odgovora kako bi korisnik znao što može očekivati. Zahtjev je URL od klijenta koji traži resurs, dok je odgovor povratna informacija s poslužitelja.

Slijedi primjer zahtjeva koji možete poslati LinkedIn API-ju.

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

Evo primjera odgovora koji može vratiti:

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

5. Parametri i zaglavlja

Također biste trebali dokumentirati parametre svojih krajnjih točaka, a to su opcije koje im možete proslijediti. Parametri mogu biti ID ili broj koji određuje količinu ili vrstu podataka vraćenih kao odgovor.

Postoje različite vrste parametara, uključujući parametre zaglavlja, putanje i niza upita. Krajnje točke mogu sadržavati različite vrste parametara.

Možete uključiti neke parametre kao zaglavlja HTTP zahtjeva. Obično su to u svrhu provjere autentičnosti poput API ključa. Evo primjera zaglavlja s API ključevima:

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

Parametre staze uključujete u tijelo krajnje točke točno na URL-u. Oni pokazuju korisniku kako i gdje postaviti parametre i kako će se pojaviti odgovor. Riječi u vitičastim zagradama su parametri.

Također možete koristiti dvotočke ili drugu sintaksu za predstavljanje parametara staze.

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

S parametrima upita morate postaviti upitnik (?) prije upita na krajnjoj točki. Svaki parametar nakon toga odvojite znakom & (&). Microsoft ima dobru dokumentaciju o Graph API-ju.

6. Kodovi grešaka i rukovanje greškama

Ponekad HTTP zahtjevi ne uspijevaju, što korisnika može zbuniti. Uključite očekivane kodove pogrešaka u dokumentaciju kako biste pomogli korisnicima da razumiju pogreške.

LinkedIn pruža standardne HTTP kodove pogrešaka za obradu pogrešaka:

7. Primjeri isječaka koda

Isječci koda bitni su dijelovi vaše dokumentacije. Korisnicima pokazuju kako integrirati API u različite jezike i formate. U dokumentaciju uključite kako instalirati i integrirati SDK-ove (komplete za razvoj softvera) na raznim jezicima.

RapidAPI ima dobre primjere isječaka koda za programere:

9. Određivanje verzija API-ja i zapisnici promjena

Verzija API-ja bitan je dio API dizajn. Osigurava nesmetano pružanje usluga vašim korisnicima. Određivanje verzija može poboljšati API novim verzijama bez utjecaja na klijentske aplikacije.

Korisnici mogu nastaviti koristiti starije verzije ili s vremenom prijeći na napredne. Ako postoje nove promjene u zapisnicima, uključite ih u dokumentaciju kako bi korisnici bili svjesni.

Microsoft Graph API ima dobro dokumentirane zapise promjena:

Na kraju, uključite važne kontakte u dokumentaciju za podršku i povratne informacije. Oni osiguravaju da vas korisnici mogu kontaktirati s izvješćima o pogreškama i informacijama o tome kako poboljšati API.

Vrijednost API dokumentacije

Ako izgradite API za komercijalnu vrijednost, potrošnja određuje njegov uspjeh. A da bi korisnici koristili vaš API, moraju ga razumjeti.

Dokumentacija oživljava API. Detaljno objašnjava komponente jednostavnim jezikom koji korisnicima prodaje svoju vrijednost i upotrebu. Korisnici će rado koristiti vaš API ako imaju izvrsno razvojno iskustvo.

Dobra dokumentacija također pomaže u pojednostavljenju održavanja i skaliranja API-ja. Timovi koji rade s API-jem mogu koristiti dokumentaciju za upravljanje njime.