10 Důležité součásti dokumentace API

Stále více organizací využívá sílu API k optimalizaci svého podnikání. Rozhraní API se stala způsobem, jak odemknout hodnotu a poskytnout další službu.

I přes jejich obecnou oblibu není každé API úspěšné. Přijetí a používání API do značné míry určuje jeho úspěch. Chcete-li zvýšit přijetí, vaše API musí být snadno k nalezení a použití.

Nejlepší způsob, jak toho dosáhnout, je podrobné zdokumentování vašeho API. To zahrnuje podrobný popis důležitých součástí, aby byly srozumitelnější. Zjistěte některé součásti, které byste měli zahrnout do dokumentace k rozhraní API.

Co je dokumentace API?

Dokumentace API je technický obsah, který podrobně popisuje API. Je to příručka obsahující všechny informace potřebné pro práci s API. Dokument pokrývá životní cyklus API a pokyny k integraci a používání jeho součástí.

Dokumentace API zahrnuje popisy prostředků, koncové body, metody, požadavky a příklady odpovědí. Může také obsahovat praktické příručky a návody, které uživatelům ukazují, jak jej integrovat. Prozkoumání každé části poskytuje uživatelům solidní znalosti o integraci a používání rozhraní API.

Editory jako Google Docs byly kdysi široce používány pro profesionální dokumentaci API. V současné době existují pokročilejší nástroje jako Document 360, Confluence a GitHub Pages. Tyto nástroje pomáhají integrovat text a kód pro snazší pracovní postupy.

1. Přehled a účel API

Prvním krokem v dokumentaci API je dát uživatelům vědět, o co jde. Uveďte informace o typu zdrojů, které poskytuje. Rozhraní API mají obvykle různé zdroje, které vracejí, takže uživatel může požadovat, co potřebuje.

Popis je stručný, obvykle jedna až tři věty popisující zdroj. Popište dostupný zdroj, koncové body a metody připojené ke každému koncovému bodu. Jako vývojář API nejlépe popíšete jeho součásti, funkčnost a případ použití.

Zde je příklad popisu rozhraní Airbnb API:

2. Metody autentizace a autorizace

Rozhraní API zpracovávají tisíce požadavků a obrovské množství dat. Autentizace je jedním ze způsobů, jak zajistit, aby data vašeho API a uživatelů byla zabezpečena před hackery. API Authentication ověřuje identitu uživatele a umožňuje jim přístup ke zdrojům.

Existuje několik způsobů, jak zajistit zabezpečení koncových bodů. Většina rozhraní API používá klíč API. Jedná se o řetězec znaků, který může uživatel vygenerovat z webu a použít k ověření.

Dokumentace API by měla uživatele vést k tomu, jak ověřit a autorizovat své identity. Následující diagram ukazuje informace o ověřování Twitter API.

3. Koncové body, vzory URI a metody HTTP

V této části ukažte, jak získat přístup ke zdroji. Koncové body zobrazují pouze konec cesty, odtud jejich název. Ukazují přístup ke zdroji a HTTP metody koncový bod interaguje, jmenovitě GET, POST nebo DELETE.

Jeden zdroj má pravděpodobně různé koncové body. Každý s jinou cestou a metodou. Koncové body mají obvykle stručný popis jejich účelu a vzor adresy URL.

Následující ukázka kódu ukazuje koncový bod uživatele GET na Instagramu.

ZÍSKAT /mě? fields={fields}&access_token={access-token}

4. Formáty požadavku a odpovědi

Musíte zdokumentovat formáty požadavku a odpovědi, aby uživatel věděl, co může očekávat. Požadavek je URL od klienta žádajícího o zdroj, zatímco odpovědí je zpětná vazba od serveru.

Následuje ukázkový požadavek, který můžete odeslat do API LinkedIn.

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

A zde je ukázková odpověď, kterou může vrátit:

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

5. Parametry a záhlaví

Měli byste také zdokumentovat parametry vašich koncových bodů, což jsou možnosti, které jim můžete předat. Parametry mohou být ID nebo číslo, které určuje množství nebo typ dat vrácených jako odpověď.

Existují různé typy parametrů, včetně parametrů záhlaví, cesty a řetězce dotazu. Koncové body mohou obsahovat různé typy parametrů.

Některé parametry můžete zahrnout jako záhlaví požadavku HTTP. Obvykle jsou to pro účely ověřování, jako je klíč API. Zde je příklad záhlaví s klíči API:

záhlaví: {
 'X-RapidAPI-Key': 'fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635',
 'X-RapidAPI-Host': 'wft-geo-db.p.rapidapi.com'
}

Parametry cesty zahrnete do těla koncového bodu přímo na adresu URL. Ukazují uživateli, jak a kam umístit parametry a jak bude vypadat odpověď. Slova ve složených závorkách jsou parametry.

K vyjádření parametrů cesty můžete také použít dvojtečky nebo jinou syntaxi.

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

S parametry dotazu musíte před dotaz na koncovém bodu umístit otazník (?). Každý parametr poté oddělte ampersandem (&). Microsoft má dobrou dokumentaci k Graph API.

6. Chybové kódy a zpracování chyb

Někdy požadavky HTTP selžou, což může uživatele nechat zmatený. Do dokumentace zahrňte očekávané chybové kódy, které uživatelům pomohou chyby pochopit.

LinkedIn poskytuje standardní chybové kódy HTTP pro zpracování chyb:

7. Ukázkové úryvky kódu

Fragmenty kódu jsou základní součástí vaší dokumentace. Ukazují uživatelům, jak integrovat API v různých jazycích a formátech. V dokumentaci uveďte, jak nainstalovat a integrovat sady SDK (sady pro vývoj softwaru) v různých jazycích.

RapidAPI má dobré příklady úryvků kódu pro vývojáře:

9. Verze API a protokoly změn

Verze API je nezbytnou součástí Návrh API. Zajišťuje nepřetržité poskytování služeb vašim uživatelům. Správa verzí může vylepšit API novými verzemi, aniž by to ovlivnilo klientské aplikace.

Uživatelé mohou nadále používat starší verze nebo včas přejít na pokročilé. Pokud jsou v protokolech nové změny, zahrňte je do dokumentace, aby o nich byli uživatelé informováni.

Microsoft Graph API má dobře zdokumentované protokoly změn:

Nakonec do dokumentace zahrňte důležité kontakty pro podporu a zpětnou vazbu. Ty zajišťují, že vás uživatelé mohou kontaktovat s chybovými zprávami a informacemi o tom, jak vylepšit API.

Hodnota dokumentace API

Pokud vytvoříte API pro komerční hodnotu, spotřeba určuje jeho úspěch. A aby uživatelé mohli používat vaše API, musí mu rozumět.

Dokumentace oživuje API. Vysvětluje komponenty podrobně jednoduchým jazykem, který uživatelům prodává jejich hodnotu a použití. Uživatelé budou šťastně využívat vaše API, pokud mají skvělé vývojářské zkušenosti.

Dobrá dokumentace také pomáhá zjednodušit údržbu a škálování API. Týmy pracující s rozhraním API mohou k jeho správě používat dokumentaci.