10 API dokumentatsiooni olulist komponenti

Üha enam organisatsioone kasutab API-de võimsust oma äri optimeerimiseks. API-dest on saanud viis väärtuse avamiseks ja lisateenuse pakkumiseks.

Vaatamata nende üldisele populaarsusele ei ole iga API edukas. API kasutuselevõtt ja kasutamine määravad suuresti selle edu. Kasutamise suurendamiseks peab teie API-t olema lihtne leida ja kasutada.

Parim viis seda teha on oma API üksikasjalik dokumenteerimine. See hõlmab kriitiliste komponentide üksikasjalikku kirjeldamist, et neid oleks lihtsam mõista. Siit leiate mõned komponendid, mida peaksite oma API dokumentatsiooni lisama.

Mis on API dokumentatsioon?

API dokumentatsioon on tehniline sisu, mis kirjeldab API-t üksikasjalikult. See on juhend, mis sisaldab kogu API-ga töötamiseks vajalikku teavet. Dokument hõlmab API elutsüklit ja juhiseid selle komponentide integreerimiseks ja kasutamiseks.

API dokumentatsioon hõlmab ressursside kirjeldusi, lõpp-punkte, meetodeid, päringuid ja vastuste näiteid. See võib sisaldada ka praktilisi juhendeid ja õpetusi, mis näitavad kasutajatele, kuidas seda integreerida. Iga jaotise uurimine annab kasutajatele hea ülevaate API integreerimisest ja kasutamisest.

Redigeerijaid, nagu Google Docs, kasutati kunagi laialdaselt professionaalseks API dokumenteerimiseks. Tänapäeval on olemas täiustatud tööriistad, nagu Document 360, Confluence ja GitHub Pages. Need tööriistad aitavad integreerida teksti ja koodi töövoogude hõlbustamiseks.

1. API ülevaade ja eesmärk

API dokumenteerimise esimene samm on kasutajatele teada andmine, millega tegu. Lisage teave pakutavate ressursside tüübi kohta. API-del on tavaliselt erinevad ressursid, mida nad tagastavad, nii et kasutaja saab taotleda seda, mida ta vajab.

Kirjeldus on lühike, tavaliselt üks kuni kolm lauset, mis kirjeldavad ressurssi. Kirjeldage saadaolevat ressurssi, lõpp-punkte ja igale lõpp-punktile lisatud meetodeid. API arendajana kirjeldate kõige paremini selle komponente, funktsioone ja kasutusjuhtumeid.

Siin on näide Airbnb API kirjeldusest:

2. Autentimis- ja autoriseerimismeetodid

API-d töötlevad tuhandeid päringuid ja tohutuid andmemahtusid. Autentimine on üks viise, kuidas tagada oma API ja kasutajate andmete turvalisus häkkerite eest. API autentimine kontrollib kasutaja identiteeti ja annab neile juurdepääsu ressurssidele.

Selle tagamiseks on mitu võimalust lõpp-punkti turvalisus. Enamik API-sid kasutab API-võtit. See on tähemärkide jada, mille kasutaja saab veebisaidilt genereerida ja autentimiseks kasutada.

API dokumentatsioon peaks juhendama kasutajaid, kuidas oma identiteeti autentida ja autoriseerida. Järgmine diagramm näitab Twitteri API autentimise teavet.

3. Lõpp-punktid, URI mustrid ja HTTP-meetodid

Selles jaotises demonstreerige, kuidas ressursile juurde pääseda. Lõpp-punktid näitavad ainult tee lõppu, sellest ka nende nimi. Need näitavad juurdepääsu ressursile ja HTTP meetodid lõpp-punkt suhtleb, nimelt GET, POST või DELETE.

Ühel ressursil on tõenäoliselt mitu lõpp-punkti. Igaühel erinev tee ja meetod. Lõpp-punktidel on tavaliselt nende eesmärgi lühikirjeldus ja URL-i muster.

Järgmine koodinäidis näitab GET-i kasutaja lõpp-punkti Instagramis.

SAADA / mind? fields={fields}&access_token={pääsuluba}

4. Taotluse ja vastuse vormid

Peate dokumenteerima päringu ja vastuse vormingud, et kasutaja teaks, mida oodata. Päring on URL kliendilt, kes küsib ressurssi, samas kui vastus on tagasiside serverilt.

Järgmine on näidistaotlus, mille saate LinkedIn API-le saata.

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

Ja siin on vastuse näidis, mille see võib tagastada:

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

5. Parameetrid ja päised

Samuti peaksite dokumenteerima oma lõpp-punktide parameetrid, mis on valikud, mida saate neile edastada. Parameetrid võivad olla ID või number, mis määrab vastuseks tagastatavate andmete hulga või tüübi.

On erinevat tüüpi parameetreid, sealhulgas päise, tee ja päringustringi parameetrid. Lõpp-punktid võivad sisaldada erinevat tüüpi parameetreid.

Saate lisada mõned parameetrid HTTP päringu päistena. Tavaliselt on need autentimise eesmärgil nagu API-võti. Siin on näide API-võtmetega päisest:

päised: {
 "X-RapidAPI-Key": "fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635",
 "X-RapidAPI-Host": "wft-geo-db.p.rapidapi.com"
}

Lisate tee parameetrid lõpp-punkti kehasse otse URL-i. Need näitavad kasutajale, kuidas ja kuhu parameetrid paigutada ning kuidas vastus ilmub. Lokkis sulgudes olevad sõnad on parameetrid.

Tee parameetrite esitamiseks võite kasutada ka kooloneid või muud süntaksit.

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

Päringu parameetrite puhul peate lõpp-punkti päringu ette panema küsimärgi (?). Pärast seda eraldage iga parameeter ampersandiga (&). Microsoftil on Graph API kohta hea dokumentatsioon.

6. Veakoodid ja vigade käsitlemine

Mõnikord ebaõnnestuvad HTTP-päringud, mis võib kasutaja segadusse ajada. Lisage dokumentatsiooni eeldatavad veakoodid, et aidata kasutajatel vigu mõista.

LinkedIn pakub vigade käsitlemiseks standardseid HTTP-tõrkekoode:

7. Koodilõikude näidised

Koodilõigud on teie dokumentatsiooni olulised osad. Need näitavad kasutajatele, kuidas API-d erinevates keeltes ja vormingutes integreerida. Lisage dokumentatsiooni, kuidas installida ja integreerida SDK-sid (tarkvaraarenduskomplekte) erinevates keeltes.

RapidAPI-l on arendajatele häid näiteid koodilõikudest:

9. API versioonide ja muudatuste logid

API versioonide loomine on selle oluline osa API disain. See tagab teie kasutajatele katkematute teenuste osutamise. Versioonide koostamine võib API-t täiustada uute versioonidega, ilma et see mõjutaks klientrakendusi.

Kasutajad saavad jätkata vanemate versioonide kasutamist või minna õigeaegselt üle täiustatud versioonidele. Kui logides on uusi muudatusi, lisage need dokumentatsiooni, et kasutajad oleksid teadlikud.

Microsoft Graph API-l on hästi dokumenteeritud muudatuste logid:

Lõpuks lisage abi ja tagasiside saamiseks dokumentidesse olulised kontaktid. Need tagavad, et kasutajad saavad teieni veaaruannete ja teabega API täiustamise kohta.

API dokumentatsiooni väärtus

Kui loote API kaubandusliku väärtuse jaoks, määrab tarbimine selle edu. Ja selleks, et kasutajad saaksid teie API-t tarbida, peavad nad sellest aru saama.

Dokumentatsioon äratab API ellu. See selgitab komponente üksikasjalikult lihtsas keeles, mis müüb kasutajatele oma väärtust ja kasutust. Kasutajad tarbivad teie API-d hea meelega, kui neil on suurepärane arendajakogemus.

Hea dokumentatsioon aitab lihtsustada ka API hooldust ja skaleerimist. API-ga töötavad meeskonnad saavad selle haldamiseks kasutada dokumentatsiooni.