Obsah
- Udělej si domácí úkol
- Být konzistentní
- Použijte OAuth
- Začněte brzy
- Napište dobrou dokumentaci
- Vývoj API: Keep It Simple
Odnést:
Vývojáři softwaru chtějí způsob, jak integrovat svůj software s vaším - a nechtějí, aby se věci rozebíraly. Zde přichází 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 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í). V tomto článku 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ě, které rozhraní API budete používat, navrhl bych jít s RESTful přístupem pomocí protokolu HTTP. Je to jednodušší než SOAP, jeho v současné době populárnější a bude jednodušší začít s používáním webového softwarového produktu.
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 souvislosti s hovorem 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
Je běžnou praxí zahrnout do výstupních dat zpět ke 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 shromažďovat přihlašovací údaje uživatele k vašemu serveru 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á přístup k pověření 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žívání 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 jeho zastoupení přístup k chráněným zdrojům, jednoduše přejde do vytvořeného rozhraní a klientův přístup zruší.
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. I když někteří vývojáři mohou mít špatně zdokumentované API a zjistit, jak má fungovat, většina z nich nechce.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ářů.