5 krokov k vytvoreniu úspešného API

Je to povaha vývoja softvéru. Vývojári vytvárajú softvér s ohľadom na koncového používateľa. Vyzerá to celkom jednoducho, ale niekedy sú títo používatelia tiež vývojármi. Nepotrebujú pre nich veci rozdelené. Nepotrebujú ani jednoduchosť. Všetko, čo chcú, je prístup - spôsob, ako integrovať váš softvér s ich. Tu prichádza rozhranie API (aplikačné programovacie rozhranie). Dúfam, že vyzdvihnem päť krokov, ktoré môžete podniknúť na vytvorenie úspešného rozhrania API.

Urob si domácu úlohu

Pokiaľ ide o vývoj softvéru, nikto z nás nechce znovu objaviť bicykel. V súčasnosti majú takmer všetky veľké webové spoločnosti API pre svoje softvérové ​​produkty. Preštudujte si tieto API a pokúste sa vyzdvihnúť rôzne návrhové rozhodnutia, ktoré sa rozhodli ich vytvoriť.

Existuje mnoho rôznych technológií, ale väčšina rozhraní API, ktoré uvidíte, bude používať buď rozhranie RESTful alebo SOAP. Ak ste na hranici toho, ktoré rozhranie API budete používať, odporúčam vám ísť s RESTful prístupom pomocou protokolu HTTP. Je to jednoduchšie ako SOAP, v súčasnosti je obľúbenejšie a pri používaní webového softvérového produktu bude jednoduchšie začať s jeho používaním.

Byť dôsledný

Jednou z vecí, ktorú vývojári najviac oceňujú, je konzistentnosť. To okrem iného zahŕňa adresovateľnosť, vstupné argumenty, výstupné formáty a spracovanie chýb.

Pri použití prístupu RESTful existuje veľa rôznych schém pomenovávania URI. Každý z nich má svojich priaznivcov, takže si jedného stačí vybrať a držať sa ho. To isté platí pre štruktúru vstupu a výstupu. Väčšina rozhraní API podporuje používanie formátov XML a JSON ako vstupných a výstupných formátov. Navrhujem podporu oboch, ale výber predvoleného formátu.

Pokiaľ ide o vstup, vaše vstupné požiadavky by sa mali pomenovať konzistentne a mali by mať zmysel v kontexte volania API, ktoré uskutočňujete. Pre výstup sa uistite, že používate bežné rozloženia dátovej štruktúry. Ak balíte výstup jedného hovoru API do a Značku XML, zvážte vykonanie ďalších hovorov.

Bežnou praxou je zahrnúť nejaký príznak stavu do výstupných údajov, ktoré odošlete späť klientovi. Ak používate prístup RESTful API, malo by sa to urobiť pomocou stavových kódov HTTP. Napríklad, ak ste práve spracovali požiadavku PUT na existujúci dátový objekt, stavový kód HTTP, ktorý uvediete vo svojej odpovedi, sa bude líšiť v závislosti od výsledku žiadosti.

Namiesto ľubovoľného príznaku, ktorý označuje stav hovoru, sa na označenie, že žiadosť bola úspešná, môže použiť štandardný stavový kód „200 OK“, zatiaľ čo stavový kód „400 zlých požiadaviek“ sa môže použiť na označenie, že žiadosť bola chybne. Existuje pomerne málo stavových kódov HTTP, ktoré sa dajú použiť v rôznych situáciách.

Použite protokol OAuth

Väčšina softvérových produktov bude vyžadovať určitý druh autentifikácie užívateľa, aby mal prístup k chráneným zdrojom pre tohto používateľa. Pokiaľ ide o rozhrania API, je nechať klienta zhromažďovať používateľské poverenia na odoslanie na váš server, čo je zlý postup. Tu prichádza OAuth.

OAuth poskytuje veľa výhod oproti autentifikácii užívateľského mena a hesla od tretej strany. Klient predovšetkým nemá nikdy prístup k povereniam používateľa. Používateľ sa presmeruje na váš server, keď sa prihlási. Po prihlásení používateľa na vašu stránku bude presmerovaný späť na klienta, kde klient dostane prístupový token, ktorý sa použije v budúcich požiadavkách na chránené zdroje.

Ďalšou dôležitou výhodou použitia protokolu OAuth je možnosť používateľa kedykoľvek zrušiť prístup klienta. Ak sa používateľ rozhodne, že z akéhokoľvek dôvodu už nechce, aby klient mal v jeho mene prístup k chráneným zdrojom, jednoducho prejde na rozhranie, ktoré ste vytvorili, a zruší prístup klienta.

Začnite skoro

Jednou z najdôležitejších vecí, ktoré môžete urobiť, aby bolo vaše API úspešné, je začať čoskoro. Keď napíšete túto funkciu a vytvoríte nejaký záznam v databáze, choďte do toho a venujte viac času a napíšte preň rozhranie API.

Napíšte dobrú dokumentáciu

Nič zabíja API rýchlejšie, ako nemá dobrú dokumentáciu. Zatiaľ čo niektorí vývojári môžu mať zle zdokumentované API a zistiť, ako to má fungovať, väčšina to nechce.

Mali by ste zdokumentovať každé volanie rozhrania API, ktoré máte k dispozícii, a kategorizovať hovory API podľa typu údajov, na ktoré reagujú. Spolu s dokumentáciou koncových bodov pre samotné volania API by ste mali systematicky definovať požadované a voliteľné vstupné argumenty, ako aj štruktúry výstupných údajov. Argumenty vstupu by mali uvádzať predvolenú hodnotu, ak existuje, a tiež by mali naznačovať očakávaný formát údajov, napríklad číslo alebo reťazec. Nakoniec by každé volanie API malo obsahovať zoznam chybových stavov a stavových kódov.

Na doplnenie dokumentácie nezabudnite pri každom volaní API uviesť jeden alebo dva príklady bežných vstupných a výstupných scenárov.

Vývoj API: Keep It Simple

Aj keď sa môže zdať, že vývoj API je komplikované úsilie, myšlienka samotného API nie je nový koncept a existuje veľké množstvo dostupnej dokumentácie ku každej téme, ktorej sa tu dotýkame. Nezabudnite použiť osvedčené postupy, kde ich nájdete, a poskytnúť konzistentné, dobre zdokumentované rozhranie.