10 svarbių API dokumentacijos komponentų

Vis daugiau organizacijų naudojasi API galia optimizuoti savo verslą. API tapo būdu atrakinti vertę ir teikti papildomą paslaugą.

Nepaisant bendro populiarumo, ne kiekviena API yra sėkminga. API priėmimas ir naudojimas daugiausia lemia jos sėkmę. Norint padidinti pritaikymą, jūsų API turi būti lengva rasti ir naudoti.

Geriausias būdas tai padaryti – išsamiai dokumentuoti API. Tai apima svarbiausių komponentų detalizavimą, kad juos būtų lengviau suprasti. Sužinokite kai kuriuos komponentus, kuriuos turėtumėte įtraukti į savo API dokumentus.

Kas yra API dokumentacija?

API dokumentacija yra techninis turinys, kuriame išsamiai aprašoma API. Tai vadovas, kuriame yra visa informacija, reikalinga darbui su API. Dokumentas apima API gyvavimo ciklą ir jo komponentų integravimo ir naudojimo instrukcijas.

API dokumentacija apima išteklių aprašymus, galutinius taškus, metodus, užklausas ir atsakymų pavyzdžius. Jame taip pat gali būti praktinių vadovų ir vadovėlių, rodančių, kaip jį integruoti. Naršydami kiekvieną skyrių naudotojai puikiai supranta API integravimą ir naudojimą.

Redaktoriai, tokie kaip „Google“ dokumentai, kadaise buvo plačiai naudojami profesionaliam API dokumentavimui. Šiais laikais yra pažangesnių įrankių, tokių kaip „Document 360“, „Confluence“ ir „GitHub Pages“. Šie įrankiai padeda integruoti tekstą ir kodą, kad būtų lengviau atlikti darbo eigą.

1. API apžvalga ir paskirtis

Pirmasis API dokumentavimo veiksmas yra leisti vartotojams žinoti, apie ką ji kalba. Įtraukite informaciją apie jo teikiamų išteklių tipą. API paprastai turi įvairių grąžinamų išteklių, todėl vartotojas gali paprašyti to, ko jiems reikia.

Aprašymas yra trumpas, paprastai nuo vieno iki trijų sakinių, apibūdinančių šaltinį. Apibūdinkite turimus išteklius, galinius taškus ir metodus, pridedamus prie kiekvieno galutinio taško. Kaip API kūrėjas geriausiai apibūdinate jos komponentus, funkcionalumą ir naudojimo atvejį.

Štai Airbnb API aprašymo pavyzdys:

2. Autentifikavimo ir autorizacijos metodai

API apdoroja tūkstančius užklausų ir didžiulius duomenų kiekius. Autentifikavimas yra vienas iš būdų užtikrinti, kad jūsų API ir vartotojų duomenys būtų apsaugoti nuo įsilaužėlių. API autentifikavimas patvirtina vartotojo tapatybę ir suteikia jiems prieigą prie išteklių.

Yra keli būdai užtikrinti galutinio taško saugumas. Dauguma API naudoja API raktą. Tai simbolių eilutė, kurią vartotojas gali sugeneruoti iš svetainės ir naudoti autentifikavimui.

API dokumentacijoje naudotojams turėtų būti paaiškinta, kaip autentifikuoti ir įgalioti savo tapatybę. Šioje diagramoje parodyta Twitter API autentifikavimo informacija.

3. Galiniai taškai, URI šablonai ir HTTP metodai

Šiame skyriuje parodykite, kaip pasiekti šaltinį. Galiniai taškai rodo tik kelio pabaigą, taigi ir jų pavadinimą. Jie rodo prieigą prie šaltinio ir HTTP metodai galutinis taškas sąveikauja su, būtent GET, POST arba DELETE.

Vienas išteklius greičiausiai turi įvairių galinių taškų. Kiekvienas turi skirtingą kelią ir metodą. Galiniai taškai paprastai turi trumpus jų paskirties aprašymus ir URL šabloną.

Šis kodo pavyzdys rodo GET vartotojo galutinį tašką „Instagram“.

Pagauk mane? fields={fields}&access_token={prieigos raktas}

4. Užklausų ir atsakymų formatai

Turite dokumentuoti užklausos ir atsakymo formatus, kad vartotojas žinotų, ko tikėtis. Užklausa yra URL iš kliento, prašančio išteklių, o atsakymas yra atsiliepimas iš serverio.

Toliau pateikiamas užklausos pavyzdys, kurį galite nusiųsti į „LinkedIn“ API.

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

Ir čia yra atsakymo pavyzdys, kurį jis gali grąžinti:

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

5. Parametrai ir antraštės

Taip pat turėtumėte dokumentuoti savo galinių taškų parametrus – parinktis, kurias galite jiems perduoti. Parametrai gali būti ID arba numeris, nurodantis atsakant grąžinamų duomenų kiekį arba tipą.

Yra įvairių tipų parametrų, įskaitant antraštės, kelio ir užklausos eilutės parametrus. Galiniuose taškuose gali būti įvairių tipų parametrų.

Kai kuriuos parametrus galite įtraukti kaip HTTP užklausų antraštes. Paprastai tai yra autentifikavimo tikslais, pavyzdžiui, API raktas. Štai antraštės su API raktais pavyzdys:

antraštės: {
 „X-RapidAPI-Key“: „fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635“,
 „X-RapidAPI-Host“: „wft-geo-db.p.rapidapi.com“
}

Kelio parametrus įtraukiate į galutinio taško turinį tiesiai URL. Jie parodo vartotojui, kaip ir kur įdėti parametrus ir kaip pasirodys atsakymas. Garbanotuose skliaustuose esantys žodžiai yra parametrai.

Taip pat galite naudoti dvitaškius ar kitą sintaksę kelio parametrams pavaizduoti.

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

Naudodami užklausos parametrus, prieš užklausą galutiniame taške turite įdėti klaustuką (?). Po to kiekvieną parametrą atskirkite ampersandu (&). „Microsoft“ turi gerą „Graph API“ dokumentaciją.

6. Klaidų kodai ir klaidų tvarkymas

Kartais HTTP užklausos nepavyksta, todėl vartotojas gali sutrikti. Į dokumentaciją įtraukite numatomus klaidų kodus, kad naudotojai suprastų klaidas.

„LinkedIn“ pateikia standartinius HTTP klaidų kodus klaidų tvarkymui:

7. Kodo fragmentų pavyzdžiai

Kodo fragmentai yra pagrindinė jūsų dokumentacijos dalis. Jie parodo vartotojams, kaip integruoti API įvairiomis kalbomis ir formatais. Į dokumentaciją įtraukite, kaip įdiegti ir integruoti SDK (programinės įrangos kūrimo rinkinius) įvairiomis kalbomis.

„RapidAPI“ turi gerų kodo fragmentų pavyzdžių kūrėjams:

9. API versijų kūrimo ir pakeitimų žurnalai

API versijų kūrimas yra esminė dalis API dizainas. Tai užtikrina nepertraukiamą paslaugų teikimą jūsų vartotojams. Versijų kūrimas gali patobulinti API naujomis versijomis nepaveikdamas kliento taikomųjų programų.

Vartotojai gali toliau naudoti senesnes versijas arba laiku pereiti prie išplėstinių. Jei yra naujų žurnalų pakeitimų, įtraukite juos į dokumentaciją, kad vartotojai apie tai žinotų.

„Microsoft Graph“ API turi gerai dokumentuotus pakeitimų žurnalus:

Galiausiai į dokumentaciją įtraukite svarbius kontaktus, kad gautumėte pagalbos ir atsiliepimų. Tai užtikrina, kad vartotojai galėtų su jumis susisiekti su klaidų ataskaitomis ir informacija apie tai, kaip patobulinti API.

API dokumentacijos vertė

Jei kuriate API komercinei vertei, vartojimas lemia jos sėkmę. Ir kad vartotojai galėtų naudoti jūsų API, jie turi tai suprasti.

Dokumentacija atgaivina API. Jame išsamiai paaiškinami komponentai paprasta kalba, parduodančia savo vertę ir naudojimą vartotojams. Naudotojai mielai naudosis jūsų API, jei turės puikią kūrėjo patirtį.

Gera dokumentacija taip pat padeda supaprastinti API priežiūrą ir mastelio keitimą. Komandos, dirbančios su API, gali naudoti dokumentus jai valdyti.