5 kroků k vytvoření úspěšného api

Je to povaha vývoje softwaru. Vývojáři vytvářejí software s ohledem na koncového uživatele. Vypadá to docela jednoduše, ale někdy jsou tito uživatelé také kolegy vývojáři. Nepotřebují pro ně věci rozložené. Nepotřebují ani potřebovat jednoduchost. Vše, co chtějí, je přístup - způsob, jak integrovat váš software s jejich. Zde přichází rozhraní API (aplikační programovací rozhraní). Doufám, že zdůrazním pět kroků, které můžete podniknout k vytvoření úspěšného rozhraní API.

Udělej si domácí úkol

Pokud jde o vývoj softwaru, nikdo z nás nechce znovu vynalézat kolo. V současné době mají téměř všechny velké webové společnosti API pro své softwarové produkty. Prostudujte si tato rozhraní API a pokuste se vyzvednout různá rozhodnutí o návrhu, která vedla k jejich vytvoření.

Existuje mnoho různých technologií, ale většina API, která uvidíte, bude používat buď rozhraní RESTful, nebo SOAP. Pokud jste na plotě, ke kterému rozhraní API budete používat, doporučuji vám jít s RESTful přístupem pomocí protokolu HTTP. Je to jednodušší než SOAP, v současné době je populárnější a při používání webového softwarového produktu bude snazší začít.

Být konzistentní

Jednou z věcí, kterou vývojáři nejvíce oceňují, je důslednost. To mimo jiné zahrnuje adresovatelnost, vstupní argumenty, výstupní formáty a zpracování chyb.

Při použití přístupu RESTful existuje mnoho různých schémat pojmenování URI. Každý z nich má své příznivce, takže si jen vyberte jednoho a držte se ho. Totéž platí pro strukturu vstupu a výstupu. Většina API podporuje použití XML a JSON jako vstupních a výstupních formátů. Navrhoval bych podporovat oba, ale zvolit výchozí formát.

Pokud jde o vstup, měly by být vaše vstupní požadavky pojmenovány konzistentně a měly by mít smysl v kontextu volání API, které provádíte. Pro výstup se ujistěte, že používáte běžné rozvržení datové struktury. Pokud obtékáte výstup jednoho volání API do a Značku XML, zvažte to s dalšími voláními.

Je běžnou praxí zahrnout do výstupních dat, které odešlete zpět klientovi, nějaký stavový příznak. Při použití přístupu RESTful API by to mělo být provedeno pomocí stavových kódů HTTP. Například, pokud jste právě zpracovali požadavek PUT na existující datový objekt, stavový kód HTTP, který zahrnete do své odpovědi, se bude lišit v závislosti na výsledku požadavku.

Namísto libovolného příznaku, který označuje stav hovoru, lze použít standardní stavový kód „200 OK“ k označení, že žádost byla úspěšná, zatímco stavový kód „400 špatný požadavek“ lze použít k označení, že žádost byla poškozený. Existuje poměrně málo stavových kódů HTTP, které lze použít v různých situacích.

Použijte OAuth

Většina softwarových produktů bude vyžadovat určitý druh ověření uživatele, aby měl přístup k chráněným zdrojům tohoto uživatele. Pokud jde o rozhraní API, nechat klienta shromáždit přihlašovací údaje uživatele k odeslání na váš server je špatný postup. Zde přichází OAuth.

OAuth poskytuje mnoho výhod oproti ověřování uživatelského jména a hesla třetí strany. Klient především nemá nikdy přístup k přihlašovacím údajům uživatele. Uživatel je přesměrován na váš server, když se přihlásí. Poté, co se uživatel přihlásí na váš web, je přesměrován zpět na klienta, kde klient obdrží přístupový token, který použije v budoucích požadavcích na chráněné zdroje.

Další důležitou výhodou použití protokolu OAuth je možnost uživatele kdykoli zrušit přístup klienta. Pokud se uživatel rozhodne, že z jakéhokoli důvodu již nechce, aby klient měl v jejich zastoupení přístup k chráněným prostředkům, jednoduše přejde na rozhraní, které jste vytvořili, a zruší přístup klienta.

Začněte brzy

Jednou z nejdůležitějších věcí, které můžete udělat, aby bylo vaše API úspěšné, je začít brzy. Když píšete tuto funkci, abyste vytvořili nějaký záznam v databázi, pokračujte a věnujte více času a napište pro ni rozhraní API.

Napište dobrou dokumentaci

Nic zabíjí API rychleji, než když nemá dobrou dokumentaci. Zatímco někteří vývojáři mohou mít špatně zdokumentované API a zjistit, jak to má fungovat, většina z nich nebude chtít.

Měli byste zdokumentovat každé volání API, které máte k dispozici, a roztřídit hovory API podle typu dat, na která působí. Spolu s dokumentováním koncových bodů pro volání API samotných byste měli systematicky definovat požadované a volitelné vstupní argumenty i struktury výstupních dat. Argumenty vstupu by měly uvádět výchozí hodnotu, pokud existuje, a také označovat očekávaný formát dat, například číslo nebo řetězec. Nakonec by každé volání API mělo obsahovat seznam chybových stavů a ​​stavových kódů.

Chcete-li svou dokumentaci doplnit, nezapomeňte do každého volání API zahrnout jeden nebo dva příklady běžných vstupních a výstupních scénářů.

Vývoj API: Keep It Simple

I když se může zdát, že vývoj API je komplikované úsilí, myšlenka samotného API není nový koncept a existuje velké množství dostupné dokumentace ke každému tématu, kterého jsme se zde dotkli. Nezapomeňte používat osvědčené postupy tam, kde je najdete, a poskytnout konzistentní, dobře zdokumentované rozhraní.