Bezbolan uvod u rad s API-jevima

Tipični API poziv

Ako radite bilo gdje u blizini industrije web razvoja, sigurno ćete čuti ova tri zloglasna pisma: A. P. I.

Oni se podjednako bacaju početnici i stručnjaci:

"Zašto moram upućivati ​​API? Ima li broj? "

"Jednostavan poziv ovom API-ju treće strane ovdje će učiniti trik."

"Izgradit ćemo vam RESTful API; pazite da se vaš novi sustav dobro igra s drugim uslugama. "

Iako API-ji na početku mogu izgledati zastrašujuće, oni mogu doslovno promijeniti vaš život kao programera.

Zašto? Pa, učenje ispravne upotrebe API-ja može pojednostaviti, ubrzati i ojačati vaš razvojni tijek rada. Izgradnja ili integracija API-ja donosi koristi i klijentima i vama.

Kao programeri često čujete savjet: "ne izmislite kotačić".

Šalu na stranu, API-ji igraju značajnu ulogu u tome da ne izmislite kotač. Razumijevanje osnova API-ja ključna je vještina za moderne web programere. U ovom postu pomoći ću vam da učinite upravo to. Pokrivat ćemo:

  • Prednosti upotrebe API-ja
  • Što je zapravo API
  • Koje vrste API-ja postoje
  • Slučajevi praktične uporabe

Zaronimo u to, zar ne?

Zašto koristiti API-je?

Izradite svoje razvojne vještine pomoću API-ja

Jedna od prvih velikih prekretnica u mojoj programskoj karijeri bilo je pravilno razumijevanje API-ja. Još uvijek ih koristim svaki dan.

Prije nego što zakoračim u brašno, prvo vas uvjerim da razumijevanje API-ja vrijedi vašeg vremena. Kako to?

Budući da učenje upotrebe API-ja drastično povećava vašu učinkovitost razvoja.

Prvo, omogućava vam korištenje postojeće logike koju ne morate pisati. Neke stvari koje možda jednostavno ne biste mogli sami kodirati! Da biste uštedjeli dragocjeno vrijeme kao programeru, važno je imati ideju kako izgleda pejzaž API-ja.

Drugo, mnoge razvojne probleme s kojima ćete se susresti već je riješio nekoga prije vas.

Ova postojeća rješenja mogu biti FaaS, knjižnice, web usluge, SDK-ovi, API-ji sadržaja. Bez obzira na to koji oblik imaju, najvjerovatnije će vam trebati API koji će komunicirati s njima.

Što su točno API-ji?

Web API-ji, slika s MS-a

Službena (zastrašujuća) definicija ide ovako:

U računalnom programiranju sučelje aplikacijskog programiranja (API) skup definicija podprograma, protokola i alata za izgradnju aplikacijskog softvera. Općenito govoreći, to je skup jasno definiranih metoda komunikacije između različitih komponenti softvera. Dobar API olakšava razvoj računalnog programa pružanjem svih građevnih blokova koje programer sastavlja.

Malo teška, ha? Snimimo akademsku prozu. Evo prijateljske definicije API-ja za kućnu upotrebu:

Jednostavno rečeno, API deklarira sučelje za interakciju s njegovom logikom, bez potrebe da znate što se događa ispod haube. Ova se definicija odnosi na jezik, protokol ili okruženje u kojem se nalazite. Jedini je zahtjev da se to dogodi na programskoj razini. Više o tome u nastavku.

Da biste bacili još bolju svjetlost na API-je, nabrojmo što NISU:

  • API nije nužno vanjska usluga. Na primjer, u rješenje možete uključiti knjižnice ili ih koristiti putem API-ja.
  • API nije samo sučelje. To je i specifikacija / format i implementacija.
  • API nije GUI (grafičko korisničko sučelje). API ne vrši interakcije na grafičkoj razini. Radi isključivo na programskom sloju. To može biti kroz programski jezik ili komunikacijski protokol.

Različite vrste API-ja

Svi API-i nisu stvoreni jednakim.

Iako većinom dijele isti cilj, neki ga postižu znatno bolje nego drugi. Kako bi ovo trebalo biti gladak uvod, neću se baviti onim što čini API boljim od drugih.

Imajte na umu da ljudi imaju stvarno različite pristupe za izgradnju API-ja. Ako vas predmet zanima, Google oko "API dizajnerskih obrazaca" i "API paradigmi." Ili samo započnite s ovim urednim člankom na razini ulazne razine. :)

Krajnje točke

Cilj API-ja je olakšati vam život programeru. Kako to rade?

Agregiranjem značajki / funkcija postavljenih zajedno i otkrivanjem ovih funkcionalnosti putem krajnjih točaka. To su obično URL obrasci koji se koriste za komunikaciju s API-jem.

Te su krajnje točke jedini način na koji možete komunicirati s bilo kojim API-jem. Svaka krajnja točka imat će određeni format i za svoje zahtjeve i za odgovore. Taj će format obično biti definiran u API-jevoj dokumentaciji.

Krajnje točke mogu biti jednostavne funkcije. Ili se mogu sastojati od mnogih funkcija koje mogu upućivati ​​druge API-je i tako dalje.

Ovdje je ključno da je temeljna logika tih funkcija u potpunosti apstrahirana. Ne trebate nikakvo znanje o onome što se događa u njima da biste ih koristili.

Sve dok koristite odgovarajući format, moći ćete ih konzumirati. Ovdje je "konzumirati" maštovit način da kažete "korištenje dijelova za vašu aplikaciju".

Dno crta je ovo: API je poput svakog sučelja.

Za usporedbu, svjetlosni prekidač će upaliti svjetlo, bilo da znate kako djeluju električne struje ili ne. (Kao mlada odrasla osoba, također sam naučila da morate platiti račun za struju da bi to moglo funkcionirati ... ali to je drugačija priča ...)

Kako se koriste API-ji: praktični primjeri

Zamijenimo teoriju za jednostavnu praksu sada.

Čitanje API dokumentacije

Ne želim previše pretjerivati ​​s konceptualnim objašnjenjima. Umjesto toga, analizirajmo stvarno jasan API. Vidjet ćemo kako to funkcionira u stvarnom scenariju. Za to ćemo koristiti izvorni JavaScript Math objekt. Ovdje možete pročitati njegovu dokumentaciju.

Dokumenti objašnjavaju kako svaka funkcija Math objekta opisuje kakav bi trebao biti ulazni format. Na primjer, to može biti broj ili niz brojeva.

Dokumenti također opisuju format izlaza.

Opazite kako se ništa ne spominje o logici koja se koristi za pokretanje ovih funkcija.

Na primjer, ako pokrenete konzolu preglednika i upišete Math.sqrt (bez izvršavanja funkcije), vidjet ćete nešto poput:

ƒ sqrt () {[izvorni kod]}

To je duh API-ja. Bez obzira zovete li jedan od API-ja vašeg operativnog sustava ili internetski API, ta će se načela zadržati.

Osnovni primjeri slučajeva upotrebe API-ja

Postoji puno stvari koje se mogu učiniti s popularnim dobavljačima API-a.

API Google Maps često se koristi za izgradnju boljeg korisničkog iskustva s podacima temeljenim na mapiranju u stvarnom vremenu i prometnim signalima. Twitter API može se koristiti za filtriranje i prikazivanje ciljanih tweetova u stvarnom vremenu.

Sumnjam da su mnogi od vas više zainteresirani za internetske API-je nego išta drugo. Zato zavirimo u konkretne slučajeve upotrebe.

Pomoću poštara koristiti ćemo se u našim primjerima. Ovaj odmorski klijent povezan je s web okruženjem, ali takvi alati obično postoje i u drugim okruženjima. Vrijedno je razgledati alate predviđene za određeno okruženje prije nego se počnete igrati s njima. To vam može uštedjeti puno vremena.

Ako želite slijediti dalje, trebat ćete preuzeti klijent poštara.

Konzumiranje javnog API-ja za prikupljanje podataka

Naš prvi primjer bit će prilično jednostavan, ali još zanimljiviji od matematike.

Koristit ćemo API za pse!

Ne samo da je smiješan API, već ne zahtijeva nikakvu provjeru autentičnosti.

Osim toga, to je HTTP REST API. To znači da se radi o internetskom API-ju. Budući da je povezan s ovim okruženjem, zahtijeva od nas da se pridržavamo nekih specifičnosti protokola.

U ovom slučaju, to znači korištenje HTTP glagola poput GET, PUT, POST, DELETE.

Za naš primjer, stvari ćemo jednostavno i upotrebljavati samo glagol GET. API ionako ne podržava ništa drugo. Većina javnih API-ja omogućuje vam samo konzumiranje podataka, a ne objavljivanje bilo kojeg.

Upalimo poštara i pogledajmo kako izgleda njegov sučelja.

Moje korisničko sučelje koristi tamnu temu pa se može malo razlikovati od vaše.

Ovdje će se na početku možda probaviti puno informacija, pa krenimo s VERB-om i URL-om.

Zadani glagol treba biti GET. Ako je tako, možete ga zadržati na ovaj način i unesite sljedeći URL: https://dog.ceo/api/breeds/list/all

Pritisnite "Pošalji" i prasak! Trebali biste dobiti odgovor s odgovarajućim podacima. Evo ga! Upravo ste uputili svoj prvi API poziv.

Sada, za ovaj primjer, nećemo koristiti nijedan od primljenih podataka. Ali ti ideš. Korisniku možete pokazati različite pasmine pasa i prikazati sliku određene pasmine ako klikne na nju.

Možete se igrati s različitim rutama u njihovoj dokumentaciji i upoznati se s okolinom.

Sjajna činjenica: ovaj mali projekt je također open source, pa ovdje možete pogledati ispod haube.

Rukovanje autentifikacijom privatnim API-jem

Nadamo se da ćete sada bolje razumjeti kako različiti dijelovi djeluju zajedno kad su u pitanju API-ji. Napravimo složeniji vodič koji uključuje provjeru autentičnosti. Ovdje ću koristiti jedan od svojih vlastitih API-ja.

Ovdje ćemo kôd koristiti samo za interakciju sa Snipcartovim API-jem. Možete zatvoriti poštara, ali držite ga pri ruci. Dobro je koristiti takav alat kada započinjete s API-jem.

Cilj će biti stvaranje jednostavnog alata za sučelje naredbenog retka (CLI) za stvaranje jednokratnih popusta na upotrebu kupaca. Ti će se popusti generirati putem API-ja. Sve će se to u potpunosti dogoditi na vašem računalu.

Stvorite novu mapu za ovaj projekt. Upotrijebite npm init u mapi i pokrenite uređivač teksta.

Sada stvorite datoteku index.js, a zatim otvorite package.jsonfile. U nju dodajte sljedeće retke u objekt gornje razine:

"bin": {"popusti": "./index.js"}

Trebat će nam i zapovjednički paket da bismo analizirali ulaze od klijenta. Pokrenite npm install - spremite zapovjednika u trenutnoj mapi.

Koristit ćemo i mali lib za izradu ID-ova. Možete ga instalirati pomoću npm install --sara shorttid.

Dok smo kod njega, pokrenimo i npm install - spremite lib lib zahtjev. To će nam olakšati obavljanje HTTP poziva. Vratite se na svoju datoteku index.js i zalijepite ovaj kôd:

Ovdje ćemo se usredotočiti na funkciju zahtjeva

Ovdje upućujemo vanjski API poziv Snipcartu. Možete vidjeti kako prenosimo metodu: "POST" metodi. To je zato što želimo POSTITI podatke u Snipcartov API. Specificirajući ovu metodu, API će ispravno preslikati radnju. Ovim se omogućuje čitanje tijela zahtjeva tamo gdje se nalaze podaci o popustu.

Uzbudljiva značajka API-ja koju još nismo koristili je provjera autentičnosti.

Naši drugi primjeri bili su svi na javnim API-jima. Za njih nije potrebna provjera autentičnosti.

Ali u stvarnom životu većina API-ja koje koristite vjerojatno će zahtijevati određenu provjeru autentičnosti. To je standardni "obrazac" u svijetu API-ja. Naši kupci ne bi bili sretni ako bismo dozvolili bilo kome da stvara popuste na svojoj radnji! )

U našu svrhu ključ API-a prosljeđujemo izravno u zahtjevu.

Hooray - poslužitelj nas prepozna! Tada može izvršiti zahtjev samo na naš račun.

Ako želite testirati našu malu aplikaciju, možete pokrenuti npm install -g u direktoriju projekata. Zatim jednostavno pokrenite popuste x kako biste stvorili popuste x broj puta.

Možete otići na svoju nadzornu ploču Snipcart (zauvijek besplatni računi u načinu rada Test) i sami se uvjeriti da su popusti pravilno stvoreni.

Možete zamisliti koliko to moćno može biti. Ako biste trebali stvoriti 200 tih popusta, ovo bi zahtijevalo previše vremena za to putem našeg korisničkog sučelja.

Kad ste upoznati s funkcioniranjem API-ja, to se može učiniti za nekoliko minuta. Kôd se također može višekratno upotrijebiti, tako da ako trebate učiniti isto to već mjesec dana, pa ... već ste spremni!

Zatvaranje misli

Iskreno se nadam da će vam ovaj temeljni premaz pomoći da bolje shvatite što su API-ji i kako ih možete iskoristiti u svom razvojnom procesu.

Nekoliko poteza:

  • API-ji će ubrzati vašu brzinu i proširiti opseg razvoja. Upotrijebi ih!
  • API-ji NIJE nužno vezani za web ekosustav. Vidjet ćete ih svugdje.
  • Uvijek provjerite dokumentaciju API-ja koji želite koristiti.
  • Uvijek pretražite postojeće alate (API-je ili druge) u vašem ekosustavu prije nego što počnete kodirati.

Naš posljednji primjer nije "proizvodnja" spremna. Ali vam daje dobru ideju kako bi stvari mogle izgledati u stvarnom životu.

Puno je stvari koje bismo mogli poboljšati. Na primjer:

  • Omogućavanje korisniku da odabere vrstu popusta
  • Također bismo mogli stvoriti stvorene kodove putem e-pošte izravno u istoj funkciji, umjesto da ih samo zapisujemo.
  • Da imamo napredne potrebe za našim alatima za popuste, sami bismo mogli napisati API. Odatle smo čak mogli stvoriti korisničko sučelje koje djeluje s našim API-jem da to želimo. U svakom slučaju, nadam se da ćete odmah dobiti ideju! :)

Pa, koji je sljedeći korak? Kao i gotovo sve u razvojnoj sferi, morat ćete još malo kodirati, kodirati, kodirati! Tako ćete se upoznati sa upravljanjem i integracijom API-ja.

Nakon nekog vremena postat ćete efikasni s njima.

I tu počinje prava zabava.

Ako ste uživali u ovom postu, pričekajte i podijelite ga na Twitteru. Imate komentara, pitanja? Pritisnite odjeljak ispod!

Prvotno sam ovo objavio na blogu Snipcart i podijelio to u našem biltenu.