Bezbolestné úvod do práce s API

Typické volanie rozhrania API

Ak pracujete kdekoľvek v okolí odvetvia vývoja webových aplikácií, určite budete počuť tieto tri neslávne známe listy: A. P. I.

Hádajú sa začiatočníci aj odborníci:

„Prečo musím uskutočniť API rozhranie? Má číslo? “

„Jednoduchým volaním do rozhrania API tejto tretej strany sa to podarí.“

„Vytvoríme vám RESTful API; uistite sa, že váš nový systém hrá dobre s ostatnými službami. “

Aj keď sa API môžu zdať zastrašujúce, môžu doslova zmeniť váš život vývojára.

Prečo? Naučiť sa správne používať rozhrania API môže zjednodušiť, urýchliť a posilniť vývojový postup. Vytvorenie alebo integrácia rozhraní API prináša výhody pre klientov aj pre vás.

Ako vývojári často počúvate rady: „nevymieňajte koleso“.

Okrem vtipov zohrávajú API dôležitú úlohu pri opätovnom objavovaní kolesa. Pochopenie základov API je pre moderných vývojárov webu rozhodujúcou zručnosťou. V tomto príspevku vám s tým pomôžeme. Pokryjeme:

  • Výhody používania API
  • Čo skutočne API je
  • Aké typy API existujú
  • Praktické prípady použitia

Poďme sa do toho ponoriť, však?

Prečo používať API?

Zvyšte svoje dev zručnosti pomocou API

Jedným z prvých veľkých míľnikov v mojej programovej kariére bolo správne pochopenie rozhraní API. Stále ich používam každý deň.

Predtým, ako vstúpim do dusného štrku, dovoľte mi najprv vás presvedčiť, že porozumenie API je dobre hodné vášho času. Ako to?

Pretože naučiť sa používať API výrazne zvyšuje efektívnosť vášho vývoja.

Po prvé, umožňuje vám využiť existujúcu logiku, ktorú nemusíte písať. Niektoré veci, ktoré by ste jednoducho nedokázali sami kódovať! Ak chcete ušetriť drahocenný čas vývojára, je dôležité mať predstavu o tom, ako vyzerá rozhranie API.

Po druhé, veľa problémov s vývojom, s ktorými sa stretnete, už niekto vyriešil pred vami.

Týmito existujúcimi riešeniami môžu byť FaaS, knižnice, webové služby, SDK, obsahové API. Nech už budú mať akýkoľvek tvar, s najväčšou pravdepodobnosťou budete potrebovať rozhranie API, ktoré s nimi bude pracovať.

Čo sú presne API?

Web API, obrázok z MS

Oficiálna (skľučujúca) definícia je nasledovná:

V počítačovom programovaní je aplikačné programovacie rozhranie (API) sada definícií podprogramov, protokolov a nástrojov na vytváranie aplikačného softvéru. Vo všeobecnosti ide o súbor jasne definovaných metód komunikácie medzi rôznymi softvérovými komponentmi. Dobré API uľahčuje vývoj počítačového programu poskytnutím všetkých stavebných blokov, ktoré potom programátor zostaví.

Trochu ťažké, čo? Zoberme akademickú prózu do zárezu. Toto je priateľskejšia definícia rozhrania API pripravená doma:

Jednoducho povedané, API deklaruje rozhranie, ktoré umožňuje interakciu s jeho logikou bez toho, aby ste museli vedieť, čo sa deje pod kapotou. Táto definícia sa vzťahuje na akýkoľvek jazyk, protokol alebo prostredie, v ktorom sa práve nachádzate. Jedinou požiadavkou je, aby sa to stalo na programovej úrovni. Viac o tom nižšie.

Aby sme ešte lepšie objasnili API, poďme vymenovať, čo NIE JE:

  • Rozhranie API nemusí byť nevyhnutne externou službou. Knižnice môžete napríklad zahrnúť priamo do svojho riešenia ALEBO ich použiť prostredníctvom rozhrania API.
  • Rozhranie API nie je iba rozhranie. Je to špecifikácia / formát a implementácia.
  • API nie je GUI (grafické užívateľské rozhranie). Rozhranie API nerobí interakcie na grafickej úrovni. Funguje iba na programovej vrstve. Môže to byť buď prostredníctvom programovacieho jazyka alebo prostredníctvom komunikačného protokolu.

Rôzne typy rozhraní API

Všetky API nie sú vytvorené rovnako.

Aj keď väčšinou zdieľajú rovnaký cieľ, niektorí dosahujú lepšie výsledky ako ostatní. Pretože to má byť hladké úvod, nebudem sa venovať tomu, čo robí API lepším ako ostatní.

Majte na pamäti, že ľudia majú skutočne odlišné prístupy k vytváraniu rozhraní API. Ak vás tento predmet zaujíma, spoločnosť Google sa zaujíma o „vzory dizajnu API“ a „paradigmy API“. Alebo len začnite týmto elegantným článkom na základnej úrovni. :)

Endpoints

Cieľom rozhraní API je uľahčiť vám život vývojára. Ako to robia?

Agregáciou funkcií / funkcií spojených dohromady a odhalením týchto funkcií prostredníctvom koncových bodov. Zvyčajne ide o vzory adries URL používané na komunikáciu s API.

Tieto koncové body sú jediným spôsobom interakcie s akýmkoľvek rozhraním API. Každý koncový bod bude mať určený formát tak pre svoje požiadavky, ako aj pre odpovede. Obvykle nájdete tento formát definovaný v dokumentácii API.

Koncové body môžu byť jednoduché funkcie. Alebo sa môžu skladať z mnohých funkcií, ktoré môžu volať iné API a tak ďalej.

Kľúčovým bodom je, že základná logika týchto funkcií je úplne abstrahovaná. Na ich použitie nepotrebujete žiadne znalosti o tom, čo sa v nich deje.

Pokiaľ použijete správny formát, budete ich môcť konzumovať. Tu je „konzumovať“ fantastický spôsob, ako povedať „použitie ich častí pre vašu aplikáciu“.

Zrátané podčiarknuté je to, že API je ako každé rozhranie.

Na porovnanie, svetelný spínač zapne svetlo, či viete, ako elektrické prúdy fungujú alebo nie. (Ako mladý dospelý som sa tiež dozvedel, že musíte zaplatiť účet za elektrinu, aby fungoval ... ale to je iný príbeh ...)

Ako používať API: praktické príklady

Poďme si vymeniť teóriu za ľahkú prax.

Čítanie dokumentácie API

Nechcem príliš rozširovať koncepčné vysvetlenia. Namiesto toho analyzujme skutočne jednoduché API. Uvidíme, ako to funguje v reálnom scenári. Na tento účel použijeme natívny objekt JavaScript Math. Jeho dokumentáciu si môžete prečítať tu.

Dokumenty vysvetľujú, ako každá funkcia matematického objektu popisuje, aký by mal byť vstupný formát. Môže to byť napríklad číslo alebo pole čísel.

Dokumenty tiež popisujú formát výstupu.

Všimnite si, ako sa nič nespomína v súvislosti s logikou použitou na vykonávanie týchto funkcií.

Napríklad, ak spustíte konzolu prehľadávača a napíšete Math.sqrt (bez vykonania funkcie), uvidíte niečo ako:

ƒ sqrt () {[natívny kód]}

To je duch API. Či už voláte jedno z rozhraní API vášho operačného systému alebo webové rozhranie, tieto zásady zostanú zachované.

Základné príklady prípadov použitia API

Tam je veľa vecí, ktoré možno urobiť s populárnymi poskytovateľmi rozhrania API.

Rozhranie Google Maps API sa často používa na vytváranie lepších používateľských skúseností s údajmi založenými na mapovaní v reálnom čase a dopravných signáloch. Rozhranie Twitter API sa dá použiť na filtrovanie a zobrazovanie cielených tweetov v reálnom čase.

Teraz mám podozrenie, že mnohí z vás majú väčší záujem o webové rozhrania API ako o čokoľvek iné. Poďme sa teda venovať konkrétnym prípadom použitia.

V našich príkladoch použijeme Postman. Tento Rest Client je viazaný na webové prostredie, ale takéto nástroje zvyčajne existujú aj v iných prostrediach. Predtým, ako s nimi začnete hrať, je potrebné sa oboznámiť s nástrojmi poskytnutými pre dané prostredie. To vám môže ušetriť veľa času.

Ak chcete postupovať ďalej, musíte si stiahnuť klienta Postmana.

Na získanie údajov je potrebné verejné API

Náš prvý príklad bude pomerne jednoduchý, ale ešte zaujímavejší ako matematický.

Budeme používať rozhranie Dog API!

Nie je to iba zábavné API, ale nevyžaduje sa ani žiadna autentifikácia.

Navyše je to rozhranie HTTP REST API. To znamená, že ide o webové rozhranie API. Keďže je viazaná na toto prostredie, vyžaduje si, aby sme sa prispôsobili niektorým špecifickostiam protokolu.

V tomto prípade to znamená použitie HTTP slovies ako GET, PUT, POST, DELETE.

V našom príklade budeme veci udržiavať jednoduché a budeme používať iba sloveso GET. Rozhranie API rovnako nepodporuje nič iné. Väčšina verejných rozhraní API vám umožňuje iba spotrebovávať údaje a nezverejňovať žiadne.

Poďme spustiť Postmana a uvidíme, ako vyzerá jeho používateľské rozhranie.

Moje používateľské rozhranie používa temnú tému, takže sa môže mierne líšiť od vašej.

Na začiatku by tu mohlo byť veľa informácií, takže začnime s VERB a URL.

Predvolené sloveso by malo byť GET. Ak áno, môžete si ho ponechať týmto spôsobom a zadať nasledujúcu adresu URL: https://dog.ceo/api/breeds/list/all

Hit "Odoslať" a tresk! Mali by ste dostať odpoveď s príslušnými údajmi. Voila! Práve ste uskutočnili prvé volanie rozhrania API.

Teraz pre tento príklad nebudeme používať žiadne z prijatých údajov. Ale dostanete predstavu. Používateľovi by ste mohli ukázať rôzne plemená psov a ak naň kliknú, môžete zobraziť obrázok daného plemena.

Môžete sa pohrať s rôznymi trasami v ich dokumentácii, aby ste sa oboznámili s prostredím.

Skvelá skutočnosť: tento malý projekt je tiež otvoreným zdrojom, takže sa môžete pozrieť pod kapotu.

Spracovanie overovania pomocou súkromného rozhrania API

Dúfajme, že teraz lepšie pochopíte, ako rôzne časti spolupracujú, pokiaľ ide o API. Urobme komplexnejší návod, ktorý obsahuje autentizáciu. Budem tu používať jednu z „mojich“ vlastných API.

Tu použijeme kód iba na interakciu s rozhraním API spoločnosti Snipcart. Postman môžete zavrieť, ale majte ho po ruke. Je dobré použiť takýto nástroj, keď začínate s API.

Cieľom bude vytvoriť nástroj jednoduchého rozhrania príkazového riadka (CLI) na vytvorenie jednorazovej zľavy na používanie pre nakupujúcich. Tieto zľavy sa vygenerujú prostredníctvom rozhrania API. To všetko sa stane úplne na vašom počítači.

Vytvorte nový priečinok pre tento projekt. Použite npm init v priečinku a spustite textový editor.

Teraz vytvorte súbor index.js a potom otvorte súbor package.jsonfile. V ňom pridajte do objektu najvyššej úrovne tieto riadky:

"bin": {"zľavy": "./index.js"}

Potrebujeme tiež balík veliteľov, ktorý analyzuje vstupy od klienta. Spustiť npm install - uložiť veliteľa v aktuálnom priečinku.

Na vytvorenie ID tiež použijeme malé lib. Môžete ho nainštalovať pomocou npm install --save shortid.

Keď sme na tom, spustime tiež inštaláciu npm - ušetrite žiadosť lib. Uľahčí nám to uskutočňovanie hovorov HTTP. Choďte späť do súboru index.js a prilepte tento kód:

Zamerajme sa len na funkciu žiadosti.

Na tomto mieste uskutočňujeme externé API volanie na Snipcart. Môžete vidieť, že metódu odovzdáme „POST“. Je to preto, že chceme POST údaje do rozhrania API spoločnosti Snipcart. Zadaním tejto metódy API správne zmapuje akciu. To mu umožňuje prečítať časť žiadosti, v ktorej sa nachádzajú údaje o zľavách.

Zaujímavou funkciou rozhrania API, ktorú sme zatiaľ nepoužili, je overenie totožnosti.

Našimi ďalšími príkladmi boli všetky verejné API. Tieto nevyžadujú žiadnu autentifikáciu.

V skutočnosti však väčšina rozhraní API, ktoré budete používať, bude pravdepodobne vyžadovať určité overenie. Je to štandardný „vzor“ vo svete API. Naši zákazníci by neboli spokojní, ak by sme dovolili niekomu, aby vytvoril zľavy na svoj obchod! ;)

Z tohto dôvodu odovzdávame kľúč API priamo v žiadosti.

Hurá - server nás pozná! Potom môže vykonať žiadosť s dosahom iba na náš účet.

Ak chcete otestovať našu malú aplikáciu, môžete spustiť npm install -g v adresári projektu. Potom jednoducho spustite zľavy x a vytvorte zľavy x-krát.

Môžete ísť na svoj informačný panel Snipcart (navždy bezplatné účty v testovacom režime) a presvedčte sa sami, že zľavy boli vytvorené správne.

Dokážete si predstaviť, aké silné to môže byť. Keby ste museli vytvoriť 200 z týchto zliav, vyžadovalo by to príliš veľa času na to, aby ste to urobili prostredníctvom nášho používateľského rozhrania.

Keď viete, ako API fungujú, môžete to urobiť v priebehu niekoľkých minút. Kód je tiež opakovane použiteľný, takže ak to budete musieť urobiť to isté o mesiac, dobre ... ste už nastavený!

Záverečné myšlienky

Naozaj dúfam, že tento primer vám pomohol lepšie pochopiť, čo sú API a ako ich môžete využiť vo svojom vývojovom pracovnom postupe.

Niekoľko jedál s sebou:

  • Rozhrania API urýchlia vašu rýchlosť a rozšíria rozsah vášho rozvoja. Použi ich!
  • API nie sú nevyhnutne viazané na webový ekosystém. Uvidíte ich všade.
  • Vždy dvakrát skontrolujte dokumentáciu k rozhraniu API, ktoré chcete použiť.
  • Pred začatím kódovania vždy vyhľadajte v ekosystéme existujúce nástroje (API alebo iné).

Náš posledný príklad nie je naozaj „produkčný“ pripravený. Poskytuje vám však dobrú predstavu o tom, ako by veci vyzerali v skutočnom prípade použitia.

Existuje veľa vecí, ktoré sme mohli vylepšiť. Napríklad:

  • Umožniť užívateľovi zvoliť typ zľavy
  • Vytvorené kódy by sme mohli poslať aj e-mailom priamo v rovnakej funkcii, namiesto ich len protokolovania.
  • Keby sme mali pokročilé potreby našich nástrojov na zľavy, mohli by sme sami napísať API. Odtiaľ by sme mohli dokonca vytvoriť používateľské rozhranie, ktoré bude spolupracovať s naším rozhraním API, ak by sme chceli. Každopádne dúfam, že teraz získate nápad.! :)

Aký je ďalší krok? Rovnako ako takmer čokoľvek vo vývojovej oblasti budete musieť kódovať, kódovať, kódovať a kódovať ešte viac! Takto sa zoznámite so správou a integráciou rozhrania API.

Po chvíli sa s nimi staneš efektívnym.

A tam začína skutočná zábava.

Ak sa vám tento príspevok páčil, urobte si chvíľku a tlieskajte ho a zdieľajte ho na Twitteri. Máte pripomienky, otázky? Zasiahnite sekciu nižšie!

Pôvodne som to uverejnil na blogu Snipcart a zdieľal som ho v našom bulletine.