10 dôležitých komponentov dokumentácie API

Viac organizácií využíva silu API na optimalizáciu svojho podnikania. Rozhrania API sa stali spôsobom, ako odomknúť hodnotu a poskytnúť ďalšiu službu.

Napriek všeobecnej popularite nie každé API je úspešné. Prijatie a používanie API do značnej miery určuje jeho úspech. Ak chcete zvýšiť osvojenie, vaše API sa musí dať ľahko nájsť a používať.

Najlepším spôsobom, ako to dosiahnuť, je podrobné zdokumentovanie vášho API. To zahŕňa podrobný popis kritických komponentov, aby boli ľahšie pochopiteľné. Zistite niektoré komponenty, ktoré by ste mali zahrnúť do dokumentácie rozhrania API.

Čo je dokumentácia API?

Dokumentácia API je technický obsah, ktorý podrobne popisuje API. Je to príručka obsahujúca všetky informácie potrebné na prácu s API. Dokument pokrýva životný cyklus API a pokyny na integráciu a používanie jeho komponentov.

Dokumentácia API pokrýva popisy prostriedkov, koncové body, metódy, požiadavky a príklady odpovedí. Môže obsahovať aj praktické príručky a návody, ktoré používateľom ukazujú, ako ho integrovať. Preskúmanie každej sekcie poskytuje používateľom solídne pochopenie integrácie a používania rozhrania API.

Editory ako Google Docs boli kedysi široko používané na profesionálnu dokumentáciu API. V súčasnosti existujú pokročilejšie nástroje ako Document 360, Confluence a GitHub Pages. Tieto nástroje pomáhajú integrovať text a kód pre jednoduchšie pracovné postupy.

1. Prehľad a účel rozhrania API

Prvým krokom pri zdokumentovaní API je dať používateľom vedieť, o čo ide. Zahrňte informácie o type zdrojov, ktoré poskytuje. Rozhrania API majú zvyčajne rôzne zdroje, ktoré vracajú, takže používateľ môže požiadať o to, čo potrebuje.

Popis je stručný, zvyčajne jedna až tri vety, ktoré popisujú zdroj. Opíšte dostupný zdroj, koncové body a metódy pripojené ku každému koncovému bodu. Ako vývojár API najlepšie opíšete jeho komponenty, funkčnosť a prípad použitia.

Tu je príklad popisu rozhrania Airbnb API:

2. Metódy autentizácie a autorizácie

Rozhrania API spracovávajú tisíce požiadaviek a obrovské množstvo údajov. Autentifikácia je jedným zo spôsobov, ako zabezpečiť, aby boli údaje vášho API a používateľov zabezpečené pred hackermi. Autentifikácia API overuje identitu používateľa a poskytuje im prístup k zdrojom.

Existuje niekoľko spôsobov, ako zabezpečiť zabezpečenie koncového bodu. Väčšina rozhraní API používa kľúč API. Toto je reťazec znakov, ktorý môže používateľ vygenerovať z webovej lokality a použiť na overenie.

Dokumentácia API by mala používateľov usmerniť, ako autentifikovať a autorizovať svoje identity. Nasledujúci diagram zobrazuje informácie o autentifikácii rozhrania Twitter API.

3. Koncové body, vzory URI a metódy HTTP

V tejto časti ukážte, ako získať prístup k zdroju. Koncové body zobrazujú iba koniec cesty, odtiaľ ich názov. Zobrazujú prístup k zdroju a HTTP metódy koncový bod interaguje, menovite GET, POST alebo DELETE.

Jeden zdroj má pravdepodobne rôzne koncové body. Každý s inou cestou a metódou. Koncové body majú zvyčajne stručný popis ich účelu a vzor adresy URL.

Nasledujúca ukážka kódu ukazuje používateľský koncový bod GET na Instagrame.

Dostaň ma? fields={fields}&access_token={access-token}

4. Formáty žiadostí a odpovedí

Musíte zdokumentovať formáty žiadosti a odpovede, aby používateľ vedel, čo môže očakávať. Požiadavka je adresa URL od klienta, ktorý žiada o zdroj, zatiaľ čo odpoveďou je spätná väzba zo servera.

Nasleduje vzorová požiadavka, ktorú môžete odoslať do API LinkedIn.

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

A tu je vzorová odpoveď, ktorú môže vrátiť:

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

5. Parametre a hlavičky

Mali by ste tiež zdokumentovať parametre vašich koncových bodov, čo sú možnosti, ktoré im môžete odovzdať. Parametre môžu byť ID alebo číslo, ktoré určuje množstvo alebo typ údajov vrátených ako odpoveď.

Existujú rôzne typy parametrov vrátane parametrov hlavičky, cesty a reťazca dotazu. Koncové body môžu obsahovať rôzne typy parametrov.

Niektoré parametre môžete zahrnúť ako hlavičky HTTP požiadaviek. Zvyčajne sú to na účely autentifikácie, ako je kľúč API. Tu je príklad hlavičky s kľúčmi API:

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

Parametre cesty zahrniete do tela koncového bodu priamo na adrese URL. Ukazujú používateľovi, ako a kam umiestniť parametre a ako bude vyzerať odpoveď. Slová v zložených zátvorkách sú parametre.

Na vyjadrenie parametrov cesty môžete použiť aj dvojbodky alebo inú syntax.

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

S parametrami dotazu musíte umiestniť otáznik (?) pred dotaz na koncový bod. Každý parameter potom oddeľte znakom ampersand (&). Microsoft má dobrú dokumentáciu o Graph API.

6. Chybové kódy a spracovanie chýb

Žiadosti HTTP niekedy zlyhajú, čo môže používateľa zmiasť. Do dokumentácie zahrňte očakávané chybové kódy, ktoré pomôžu používateľom pochopiť chyby.

LinkedIn poskytuje štandardné chybové kódy HTTP na spracovanie chýb:

7. Vzorové úryvky kódu

Útržky kódu sú základnými časťami vašej dokumentácie. Ukazujú používateľom, ako integrovať API v rôznych jazykoch a formátoch. V dokumentácii uveďte, ako nainštalovať a integrovať súpravy SDK (súpravy na vývoj softvéru) v rôznych jazykoch.

RapidAPI má dobré príklady útržkov kódu pre vývojárov:

9. Verzia API a protokoly zmien

Verzia API je nevyhnutnou súčasťou Dizajn API. Zabezpečuje poskytovanie neprerušovaných služieb vašim používateľom. Verzia môže vylepšiť API novými verziami bez ovplyvnenia klientskych aplikácií.

Používatelia môžu naďalej používať staršie verzie alebo včas prejsť na pokročilé. Ak dôjde k novým zmenám v protokoloch, zahrňte ich do dokumentácie, aby o tom boli používatelia informovaní.

Microsoft Graph API má dobre zdokumentované protokoly zmien:

Nakoniec do dokumentácie zahrňte dôležité kontakty pre podporu a spätnú väzbu. Tieto zaisťujú, že používatelia vás môžu kontaktovať s chybovými hláseniami a informáciami o tom, ako zlepšiť API.

Hodnota dokumentácie API

Ak vytvoríte API pre komerčnú hodnotu, spotreba určuje jeho úspech. A aby používatelia mohli využívať vaše API, musia mu rozumieť.

Dokumentácia oživuje API. Vysvetľuje komponenty podrobne jednoduchým jazykom, ktorý predáva svoju hodnotu a použitie používateľom. Používatelia budú s radosťou využívať vaše API, ak majú skvelú vývojársku skúsenosť.

Dobrá dokumentácia tiež pomáha zjednodušiť údržbu a škálovanie API. Tímy pracujúce s rozhraním API môžu na jeho správu používať dokumentáciu.