10 svarīgi API dokumentācijas komponenti

Vairāk organizāciju izmanto API iespējas, lai optimizētu savu uzņēmējdarbību. API ir kļuvušas par veidu, kā atbloķēt vērtību un nodrošināt papildu pakalpojumu.

Neskatoties uz to vispārējo popularitāti, ne katra API ir veiksmīga. API pieņemšana un izmantošana lielā mērā nosaka tās panākumus. Lai palielinātu adopciju, jūsu API ir jābūt viegli atrodamai un lietojamai.

Labākais veids, kā to izdarīt, ir detalizēti dokumentēt savu API. Tas ietver svarīgu komponentu detalizētu aprakstu, lai tie būtu vieglāk saprotami. Uzziniet dažus komponentus, kas jāiekļauj savā API dokumentācijā.

Kas ir API dokumentācija?

API dokumentācija ir tehniskais saturs, kas detalizēti apraksta API. Tā ir rokasgrāmata, kurā ir visa informācija, kas nepieciešama darbam ar API. Dokuments aptver API dzīves ciklu un norādījumus par tā komponentu integrēšanu un lietošanu.

API dokumentācija aptver resursu aprakstus, galapunktus, metodes, pieprasījumus un atbilžu piemērus. Tas var ietvert arī praktiskus ceļvežus un apmācības, kas parāda lietotājiem, kā to integrēt. Katras sadaļas izpēte sniedz lietotājiem skaidru izpratni par API integrēšanu un lietošanu.

Redaktori, piemēram, Google dokumenti, savulaik tika plaši izmantoti profesionālai API dokumentācijai. Mūsdienās ir daudz uzlaboti rīki, piemēram, Document 360, Confluence un GitHub Pages. Šie rīki palīdz integrēt tekstu un kodu, lai atvieglotu darbplūsmas.

1. API pārskats un mērķis

Pirmais API dokumentēšanas solis ir informēt lietotājus par to. Iekļaujiet informāciju par sniegto resursu veidu. API parasti ir dažādi resursi, ko tās atgriež, tāpēc lietotājs var pieprasīt nepieciešamo.

Apraksts ir īss, parasti no viena līdz trim teikumiem, kas raksturo resursu. Aprakstiet pieejamo resursu, beigu punktus un katram galapunktam pievienotās metodes. Kā API izstrādātājs jūs vislabāk aprakstāt tā komponentus, funkcionalitāti un lietošanas gadījumu.

Šeit ir piemērs Airbnb API aprakstam:

2. Autentifikācijas un autorizācijas metodes

API apstrādā tūkstošiem pieprasījumu un milzīgu datu apjomu. Autentifikācija ir viens no veidiem, kā nodrošināt jūsu API un lietotāju datu aizsardzību no hakeriem. API autentifikācija pārbauda lietotāja identitāti un nodrošina piekļuvi resursiem.

Ir vairāki veidi, kā nodrošināt galapunkta drošība. Lielākā daļa API izmanto API atslēgu. Šī ir rakstzīmju virkne, ko lietotājs var ģenerēt no vietnes un izmantot autentifikācijai.

API dokumentācijā lietotājiem ir jānorāda, kā autentificēt un autorizēt savu identitāti. Šajā diagrammā parādīta Twitter API autentifikācijas informācija.

3. Galapunkti, URI modeļi un HTTP metodes

Šajā sadaļā parādiet, kā piekļūt resursam. Galapunkti parāda tikai ceļa beigas, līdz ar to arī to nosaukumu. Tie parāda piekļuvi resursam un HTTP metodes galapunkts mijiedarbojas ar, proti, GET, POST vai DELETE.

Vienam resursam, iespējams, ir dažādi galapunkti. Katrs ar savu ceļu un metodi. Galapunktiem parasti ir īss to mērķa apraksts un URL raksts.

Šis koda paraugs parāda GET lietotāja galapunktu pakalpojumā Instagram.

SAŅEMT / mani? fields={fields}&access_token={access-token}

4. Pieprasījumu un atbilžu formāti

Jums ir jādokumentē pieprasījuma un atbildes formāti, lai lietotājs zinātu, ko sagaidīt. Pieprasījums ir URL no klienta, kurš pieprasa resursu, savukārt atbilde ir atgriezeniskā saite no servera.

Šis ir pieprasījuma paraugs, ko varat nosūtīt LinkedIn API.

GŪT https://api.linkedin.com/v2/{service}/1234

Un šeit ir atbildes paraugs, ko tā var atgriezt:

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

5. Parametri un galvenes

Jums arī jādokumentē galapunktu parametri, kas ir opcijas, kuras varat tiem nodot. Parametri var būt ID vai numurs, kas norāda atbildē atgriezto datu apjomu vai veidu.

Ir dažādi parametru veidi, tostarp galvenes, ceļa un vaicājuma virknes parametri. Gala punkti var saturēt dažāda veida parametrus.

Dažus parametrus varat iekļaut kā HTTP pieprasījuma galvenes. Parasti tie ir paredzēti autentifikācijas nolūkiem, piemēram, API atslēgai. Šeit ir piemērs galvenei ar API atslēgām:

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

Jūs iekļaujat ceļa parametrus galapunkta pamattekstā tieši uz URL. Tie parāda lietotājam, kā un kur novietot parametrus un kā parādīsies atbilde. Vārdi cirtainajās iekavās ir parametri.

Varat arī izmantot kolus vai citu sintaksi, lai attēlotu ceļa parametrus.

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

Izmantojot vaicājuma parametrus, galapunktā pirms vaicājuma ir jāievieto jautājuma zīme (?). Pēc tam katru parametru atdaliet ar & (&). Microsoft ir laba dokumentācija par Graph API.

6. Kļūdu kodi un kļūdu apstrāde

Dažreiz HTTP pieprasījumi neizdodas, kas var radīt lietotāja apjukumu. Iekļaujiet paredzamos kļūdu kodus dokumentācijā, lai palīdzētu lietotājiem izprast kļūdas.

LinkedIn nodrošina standarta HTTP kļūdu kodus kļūdu apstrādei:

7. Koda fragmentu paraugi

Koda fragmenti ir būtiska jūsu dokumentācijas daļa. Tie parāda lietotājiem, kā integrēt API dažādās valodās un formātos. Dokumentācijā iekļaujiet informāciju par to, kā instalēt un integrēt SDK (programmatūras izstrādes komplektus) dažādās valodās.

RapidAPI izstrādātājiem ir labi koda fragmentu piemēri:

9. API versiju un izmaiņu žurnāli

API versiju noteikšana ir būtiska sastāvdaļa API dizains. Tas nodrošina nepārtrauktu pakalpojumu piegādi jūsu lietotājiem. Versiju noteikšana var uzlabot API ar jaunām versijām, neietekmējot klientu lietojumprogrammas.

Lietotāji var turpināt izmantot vecākas versijas vai savlaicīgi migrēt uz uzlabotajām versijām. Ja žurnālos ir jaunas izmaiņas, iekļaujiet tās dokumentācijā, lai lietotāji būtu informēti.

Microsoft Graph API ir labi dokumentēti izmaiņu žurnāli:

Visbeidzot, iekļaujiet svarīgos kontaktus dokumentācijā, lai saņemtu atbalstu un atsauksmes. Tie nodrošina, ka lietotāji var ar jums sazināties ar kļūdu ziņojumiem un informāciju par API uzlabošanu.

API dokumentācijas vērtība

Ja veidojat API komerciālai vērtībai, patēriņš nosaka tā panākumus. Un, lai lietotāji varētu izmantot jūsu API, viņiem tas ir jāsaprot.

Dokumentācija atdzīvina API. Tajā ir sīki izskaidroti komponenti vienkāršā valodā, kas lietotājiem pārdod savu vērtību un lietojumu. Lietotāji ar prieku patērēs jūsu API, ja viņiem būs lieliska izstrādātāja pieredze.

Laba dokumentācija arī palīdz vienkāršot API apkopi un mērogošanu. Komandas, kas strādā ar API, var izmantot dokumentāciju, lai to pārvaldītu.