Doba čtení: 9 minut
Díky API se svět točí kolem. Vývojáři používají rozhraní API téměř každý den – podle některých odhadů stráví prací s rozhraními API neuvěřitelných více než 10 hodin týdně. To zahrnuje nejen jejich používání, ale také vyhledávání, googlování podpory, studium recenzí a samozřejmě i hrabání se v dokumentaci. To, jak srozumitelné, snadné, užitečné a podporované je vaše rozhraní API, určuje celý vývojářský zážitek (DX) – emocionální reakci vývojářů na produkt. V ekonomice API je skvělá zkušenost vývojářů zásadní. Rozhraní API, která pomáhají vývojářům uspět a je radost je používat, získají spoustu uživatelů a vyniknou nad konkurencí. A začíná to přesně v okamžiku, kdy poprvé otevřou dokumentaci.
Podívejte se na toto video, ve kterém se seznámíte s technologií API
Dnes budeme mluvit o tom, jak v dokumentaci API podpořit pozitivní zkušenosti vývojářů. Nejprve však musíme pochopit, co dělá špatnou dokumentaci API.
Co vývojáři v dokumentaci API nesnášejí
Komunita vývojářů je vášnivá. Konkrétně je vášnivá ohledně věcí, které se jim nelíbí. Pokud se jim nějaké API nelíbí, je to většinou kvůli brakové dokumentaci, i když je produkt ve skutečnosti skvělý. Zde je několik běžných problémů, které mají vývojáři s dokumentací API:
Není napsána jednoduchým lidským jazykem. To je častý problém automaticky generovaných dokumentací nebo dokumentací, které tvůrci zanedbávají. Ačkoli mnoho nástrojů pro generování dokumentace odvádí skvělou práci při komentování kódu, nemohou nahradit skutečné vysvětlení v angličtině napsané vývojářem nebo technickým spisovatelem.
Má velmi málo ukázek kódu. Jedná se o další konec spektra, kde je vysvětlení dostatek, ale ukázek skutečného kódu je minimum.
Je k dispozici pouze registrovaným uživatelům. Tento nepříliš šikovný manévr nijak neprospívá vašemu marketingu. Jen frustruje lidi, kteří chtějí vědět, co vaše API dělá, než se rozhodnou, zda ho chtějí (jako každý rozumný člověk).
Je to příliš dlouhé/nedá se to najít/přesné/nebylo to léta aktualizováno atd. Vytvoření dobré dokumentace je téměř stejně důležité jako vytvoření dobrého API. Protože špatně napsané dokumentace nebo ty, které nelze najít pouhým vygooglováním „API produktu“, znamenají selhání celého vývojového úsilí. Pokud vás to zajímá, už jsme nastínili specifika technické dokumentace obecně. Dokumentace API si však zaslouží samostatný článek. Jak tedy napsat skvělou dokumentaci API?“
Přijměte vývoj řízený specifikacemi
Vývoj řízený specifikacemi (SDD) je podobný vývoji řízenému testy, kdy pro každou funkci napíšete testovací případy a pak napíšete kód, který by jimi měl projít. Při SDD vytváříte dokumentaci nebo alespoň její některé části souběžně s budováním API, často podle určitého formátu popisu API, kterému se říká specifikace.
Specifikace API je jako šablona vaší budoucí dokumentace, jednotný jazyk, který popisuje návrh vašeho API, vysvětluje, jak funguje a co od něj můžete očekávat. Existuje několik specifikací, například RAML (RESTful API Modeling Language), OpenAPI (dříve Swagger) a API Blueprint, ale probíhá trend spojování všech specifikací pod kapotou OpenAPI.
Tyto specifikace mají předpřipravené dokumentační nástroje, které umožňují psaní a správu vašich dokumentů. Například nástroj API Console automaticky generuje dokumentaci z formátů RAML a OpenAPI a pomůže vám ji spustit ve vaší stávající webové aplikaci nebo jako samostatnou aplikaci.
API Console umožňuje vytvořit webový portál pro vaši dokumentaci API ze specifikací RAML a OpenAPI
Zdroj: Pawel Psztyc
Alternativou k tradičním řešením specifikací API, jako jsou CMS WordPress nebo Drupal, jsou produkty specifikací API s otevřeným zdrojovým kódem, vytvořené komunitou vývojářů pro komunitu vývojářů, mají parsery v různých programovacích jazycích a stálou podporu tvůrců.
Pište pro základní úroveň
Existuje důvod, proč technickou dokumentaci obvykle nepíší sami vývojáři – je to práce technických spisovatelů, odborníků na překlad technických aspektů do čitelné podoby. Ale i techničtí spisovatelé mají tendenci vypouštět do textu trochu žargonu.
Prohlášení API jako každý softwarový produkt je vytvářeno pro konkrétní publikum. Publikum pro dokumentaci je však rozsáhlé. Existují tři hlavní skupiny uživatelů dokumentace:
- vývojáři, kteří budou s dokumentací úzce spolupracovat
- rozhodující osoby, jako jsou techničtí ředitelé a architekti řešení, kteří chtějí rychle zjistit, zda bude vaše API vhodné
- pozorovatelé, jako jsou novináři, techničtí spisovatelé, a dokonce i konkurence, která nemusí vaše API nikdy použít.
A i v každé z těchto skupin jsou lidé s různými dovednostmi, rolemi a potřebami a všichni by měli mít s dokumentací pozitivní zkušenosti. Jak se na ně všechny zaměřit? Tím, že se zaměříte na nejméně zkušené uživatele. Jak tedy psát dokumentaci pro nováčky?“
Začněte spíše příležitostmi než technickými detaily. Přivítejte uživatele přesvědčivým příběhem, který vypráví, jak vaše API může obohatit jejich produkt nebo desetkrát usnadnit život vývojářům.
Dokumentace API Amazon Alexa začínají vysvětlením, co Alexa dělá a jaký přínos může klientovi přinést
Ukažte, kde začít. Dokumentace API jsou známé tím, že jsou příliš zahlcující a předpokládají, že uživatelé mají s rozhraním API rozsáhlé zkušenosti. Část věnovaná začátkům je povinná a měla by být napsána s trpělivostí pro potenciálního uživatele.
Facebook poskytuje jasný odkaz pro začátečníky a postupuje při začátcích krok za krokem
Vytvořte pokyny pro nejčastější případy použití. Pravděpodobně již víte, k jakým funkcím lidé používají vaše rozhraní API. Vytvořte samostatné oddíly, které se jim budou věnovat, a zahrňte do nich vzorové zprávy.
Používejte konverzační tón. Komunita vývojářů je uvolněná a neformální, takže neocení suchý korporátní jazyk, i když zní „profesionálněji“. Dobré dokumenty vždy mluví k lidem.
Vzdělávejte se v oblasti externích nástrojů. Pokud vaše rozhraní API vyžaduje použití a pochopení produktů a konceptů třetích stran, jako je OAuth nebo npm, uveďte odkazy na dokumentace nebo instalační příručky.
Udělejte to tak, aby se to dalo snadno naučit. Dokumentace API nejsou návodem k sestavení IKEA,;jsou zdrojem učení. Obohaťte dokumentaci o nejčastější dotazy, návody, blogy, a pokud je to možné, i o videa.
Zakomponujte do ní části, které musíte mít
V roce 2019 provedla společnost SmartBear, tvůrce nástroje Swagger, průzkum mezi vývojáři a uživateli rozhraní API. Zjistili, jaké funkce dokumentace jsou v komunitě považovány za nejdůležitější, a získali tak seznam sekcí dokumentace, které musí vývojáři mít. Některé z nich si projdeme.
SmartBear provedl průzkum mezi 3 000 odborníky na API
Příklady. Příklady jsou obvykle prezentovány jako části kódu, které jsou dostatečně užitečné, ale mohou být ještě praktičtější. Například zahrnutím přepisu polí, jako je tomu v dokumentech Medium, nebo dokonce vytvořením makety API, kterou mohou vývojáři testovat a používat pomocí skutečných volání. Mock API lze snadno sdílet prostřednictvím adresy URL nebo na GitHubu, a pokud jsou provedeny na určité úrovni podrobnosti, lze je dokonce použít ve finálním produktu.
Stav a chyby. Existují standardní stavové kódy a ty, které jsou specifické pro vaše API. Je dobré zahrnout všechny chyby, které může vaše rozhraní API vyvolat. Chyby se často umisťují na zvláštní stránku dokumentace, ale některé z nich má smysl duplikovat přímo pod koncový bod, kde se objevují nejčastěji.
Ověřování. Většina dokumentací API začíná autentizací a autorizací. Měla by obsahovat informace o tom, jak získat klíč API a jak ověřovat požadavky, včetně možných chyb, doby vypršení platnosti tokenu a vysvětlení citlivosti ověřování (v podstatě připomenutí, že klíče nelze sdílet a kde je lze použít).
Požadavky HTTP. Poskytování webových požadavků v protokolu HTTP je pro dokumentaci naprosté minimum. Obvykle se předpokládá, že vývojáři budou vědět, jak posílat požadavky HTTP ve zvoleném jazyce, ale někdy tvůrci API zahrnují požadavky v různých jazycích. To lze provést automaticky pomocí nástrojů pro specifikaci API a nástrojů pro správu API, jako je Postman.
Používejte standardní rozvržení
Používáte-li generátor dokumentace, je rozvržení již rozhodnuto za vás. Většina dokumentací API vypadá a působí stejně. Pokud jste jich několik použili, víte, jak k nové dokumentaci přistupovat. Přesto je uspořádání velkého objemu dat, jejich nalezení a snadná navigace složitým úkolem. Zde jsou některé vlastnosti nejfunkčnějšího rozvržení.
Dynamické rozvržení. Zastaralé rozhraní API poznáte podle statické dokumentace. Jedna stránka nebo dokonce dokument PDF v roce 2020 nestačí. Dynamickou dokumentaci lze snadno prohlížet, aktualizovat a přidávat do záložek.
Přilepený obsah. Ne, navigační panel neodvádí pozornost ani nekrade drahocenné místo na obrazovce. Vždy mějte obsah na očích.
Třísloupcové rozvržení. Toto rozložení se nepoužívá příliš často, ale umožňuje mít vpravo další sloupec pro příklady kódu. Samozřejmě to má smysl pouze v případě, že máte spoustu textu a chcete zvýraznit kód, aby uživatelé nemuseli rolovat sem a tam nebo přepínat mezi kartami.
Dokumenty API HubSpotu používají třísloupcové rozložení
Pro syntaxi používejte kontrastní barvy. Vývojáři stráví spoustu času prohlížením příkladů vašeho kódu, proto je udělejte čitelné a oddělte různé komponenty barvou.
Tento příklad z dokumentace Graph API společnosti Facebook také ukazuje, jak můžete použít různé karty pro výběr mezi SDK
Uložený stav posouvání. Jedná se o drobný detail, který ocení každý vývojář. Můžete také použít kotevní odkazy pro určení různých částí stránky v případě, že zkopírují adresu URL.
Podporovat zpětnou vazbu. Vaše dokumenty jsou vaším hlavním marketingovým nástrojem – pokud si je lidé oblíbí, budou používat vaše rozhraní API místo konkurenčních a budou kolem něj podporovat komunitu. Obvyklá zpráva „Byla tato stránka užitečná?“ vám dá vědět, jak dobře řešíte dotazy vývojářů, a formulář pro zpětnou vazbu bude často používán, pokud ho budete plnit.
Neopouštějte své dokumenty
Neaktuální dokumenty jsou největším nešvarem uživatelů API. Je to také jedna z nejčastějších chyb. Vývojáři často píší o aktualizacích několik dní po jejich zavedení a někdy se omezí na několik vět. Stává se to proto, že neexistuje žádný zavedený proces pro aktualizace dokumentace a nikdo za to není zodpovědný. Zde je návod, jak zajistit pravidelné a užitečné aktualizace dokumentace:
Příprava dokumentace před aktualizacemi. Udělejte z toho další krok v plánu spuštění, nezavádějte je dříve, než budete mít dobře napsané, podrobné a upravené odstavce, které aktualizace uvedou.
Pravidelně odstraňujte zastaralé údaje. Dokumenty je třeba často revidovat, alespoň jednou za několik měsíců. Funkce zpětné vazby od uživatelů vám umožní zachytit nesrovnalosti dříve a vždy by měl existovat člen týmu zodpovědný za jejich revizi a reakci na aktualizace.
Využívejte analytiku ke zlepšení dokumentace. Standardní analytika API vám prozradí, které koncové body se používají častěji, takže se můžete zaměřit na určité části dokumentace a poskytnout více užitečných informací nebo vytvořit specializované výukové programy. Sledujte případy použití, pro které se vaše rozhraní API používají, protože to vám umožní rozšířit nabídku hodnot a aktualizovat dokumentaci o další možnosti.
Skvělé příklady dokumentace API
Existuje spousta dobrých dokumentací, které můžete prozkoumat a poučit se z nich. Kromě příkladů, o které jsme se podělili v celém článku, vám přinášíme několik dalších, které si můžete užít a vzít na vědomí.
Dokumentace API média
Dokumentace API média nemusí nutně dodržovat všechna pravidla, která jsme dnes uvedli, ale jsou skvělé pro omezenou funkci, kterou toto API podporuje – zveřejňování a vyhledávání publikací na médiu. Jsou sdíleny na GitHubu, mají skutečně krátký, ale přehledný obsah se spoustou příkladů, přičemž každý je zakončen přepisem všech parametrů uvedených v kódu, včetně případných chyb. Je to pozoruhodně jednoduché, ale spolehlivé – všechny návrhy lze podat přímo na GitHubu a dokumentace je pravidelně aktualizována.
Dokumentace APIMailchimp
Mailchimp si uvědomuje, že většina jeho publika jsou marketingoví profesionálové, a používá jazyk, který umožňuje pochopit práci s jeho API i netechnickým osobám. Na první pohled má každá část stejnou strukturu:
- co koncový bod dělá a co průvodce umožní uživatelům dělat
- co budete potřebovat – všechny přístupy nebo účty, které musí uživatel nejprve získat
- co je každá funkce s textovým popisem, příkladem kódu v několika jazycích a někdy i snímky obrazovky rozhraní.
U každé části kódu je dokonce tlačítko pro kopírování – detail, který netechnici jistě ocení.
Dokumentace API společnosti Twilio
Společnost Twilio má pověstnou dobrou dokumentaci API. I když dokumentace jsou jen špičkou ledovce veškeré nápovědy, kterou Twilio sdílí – k dispozici jsou SDK v několika jazycích a ukázkové aplikace pro iOS, Android a web. Především dodržují logiku tří sloupců s kódem přímo v pravé části průvodce. Nejjednodušší akce jsou podrobně vysvětleny a obsahují spoustu odkazů na další informace a snímky obrazovek. Podporována je také zpětná vazba prostřednictvím tlačítka „Rate this page“ a odkazů na tým podpory a značku na StackOverflow.
Dokumentace API Spotify
Ačkoli jsou webové dokumenty API společnosti Spotify velmi typické, v platformě Spotify for Developers mají mnoho dalších informací. K dispozici jsou ukázky základních funkcí, makety aplikací, živé příklady vytvořené pomocí rozhraní API a widgetů Spotify, wrappery pro různé programovací jazyky a samozřejmě konzole. Konzola je v podstatě interaktivní dokumentace, do které můžete vyplnit svá (nebo ukázková) data a živě zkoumat koncové body. Výkonné produkty spolu se silnou znalostní základnou dělají ze společnosti Spotify spolehlivého partnera, se kterým vývojáři rádi spolupracují.
Zacházejte s dokumentací opatrně
Dokumentace je jediným styčným bodem, který budete mít s většinou svého publika, takže se musíte naučit komunikovat jejím prostřednictvím srozumitelně. Nejlepším tipem zde je, aby to byla něčí práce. Často se jedná o technického spisovatele, který umí mluvit s publikem s různými dovednostmi, který dokáže převést slova vývojářů do použitelných bodů a který dohlíží na včasnou údržbu a aktualizaci dokumentace. Zvládnout skvělou dokumentaci je však možné i bez odborníka ve vašich řadách. Nástroje pro správu API, jako jsou Swagger UI, Spotlight, Apiary a nástroje pro specifikaci dokumentace, mají širokou funkcionalitu, která vám pomůže vytvořit dokumentaci, kterou budou vývojáři milovat.