O introducere nedureroasă în lucrul cu API-urile

Apel API tipic

Dacă lucrați oriunde în apropierea industriei de dezvoltare web, sunteți sigur că veți auzi aceste trei scrisori infame: A. P. I.

Ei sunt aruncați deopotrivă de începători și experți:

„De ce trebuie să fac un apel API? Are un număr? ”

„Un simplu apel către această API terță parte va face aici trucul.”

„Vă vom crea o API RESTful; asigurându-vă că noul dvs. sistem joacă bine cu alte servicii. "

În timp ce API-urile pot părea mai întâi intimidante, acestea te pot schimba literalmente viața de dezvoltator.

De ce? Ei bine, învățarea utilizării corecte a API-urilor poate simplifica, accelera și consolida fluxul de lucru pentru dezvoltare. Construirea sau integrarea API-urilor aduce beneficii atât pentru clienți, cât și pentru tine.

În calitate de dezvoltatori, auziți deseori sfaturile: „nu reinventați roata”.

Glumește deoparte, API-urile joacă un rol semnificativ în faptul că nu reinventezi roata. Înțelegerea elementelor de bază ale API-urilor este o abilitate crucială pentru dezvoltatorii web moderni. În această postare, te voi ajuta să faci exact asta. Vom acoperi:

  • Avantajele utilizării unei API
  • Ce este de fapt o API
  • Ce tipuri de API există
  • Cazuri de utilizare practică

Să ne scufundăm în ea, nu-i așa?

De ce să folosesc API-urile?

Nivelați-vă abilitățile de dev cu API-urile

Una dintre primele repere mari din cariera mea de programare a fost înțelegerea corectă a API-urilor. Le mai folosesc în fiecare zi.

Înainte de a păși în fața nebuniei, permiteți-mi mai întâi să vă conving că înțelegerea API-urilor merită mult timp. Cum așa?

Deoarece învățarea utilizării API-urilor vă crește dramatic eficacitatea de dezvoltare.

În primul rând, vă permite să folosiți logica preexistentă pe care nu trebuie să o scrieți. S-ar putea să nu vă puteți codifica unele chestii! Pentru a economisi timp prețios ca dezvoltator, este important să aveți o idee cum arată peisajul API.

În al doilea rând, multe probleme de dezvoltare pe care le veți întâmpina au fost deja rezolvate de cineva înainte.

Aceste soluții existente ar putea fi FaaS, biblioteci, servicii web, SDK-uri, API-uri de conținut. Indiferent de forma pe care o iau, cel mai probabil veți avea nevoie de o API pentru a interacționa cu ei.

Ce sunt exact API-urile?

API-uri web, imagine din MS

Definiția oficială (descurajantă) merge astfel:

În programarea computerului, o interfață de programare a aplicațiilor (API) este un set de definiții de subrutină, protocoale și instrumente pentru construirea de aplicații software. În termeni generali, este un set de metode de comunicare clar definite între diverse componente software. O API bună face mai ușor să dezvolți un program de calculator prin furnizarea tuturor blocurilor de construcții, care sunt apoi alcătuite de programator.

Un pic greu, nu? Să luăm proza ​​academică pe o notă. Iată o definiție API mai gătită, gătită acasă:

Mai simplu spus, o API declară o interfață pentru a interacționa cu logica sa, fără a fi nevoie să știți ce se întâmplă sub capotă. Această definiție se aplică oricărui limbaj, protocol sau mediu în care vă aflați. Singura cerință este ca aceasta să se întâmple la nivel programatic. Mai multe despre asta mai jos.

Pentru a arunca o lumină și mai bună asupra API-urilor, să enumerăm ce NU SUNT:

  • O API nu este neapărat un serviciu extern. De exemplu, puteți include bibliotecile direct în soluția dvs. sau le puteți utiliza printr-o API.
  • O API nu este doar o interfață. Este atât specificația / formatul, cât și implementarea.
  • O API nu este o GUI (interfață grafică de utilizator). O API nu face interacțiuni la nivel grafic. Funcționează exclusiv pe stratul programatic. Acest lucru poate fi fie printr-un limbaj de programare, fie printr-un protocol de comunicare.

Diferite tipuri de API

Toate API-urile nu sunt create egale.

Chiar dacă în mare parte împărtășesc același obiectiv, unii îl ating mult mai bine decât alții. Întrucât aceasta va fi o introducere simplă, nu mă voi arunca în ceea ce face o API mai bună decât altele.

Rețineți că oamenii au abordări cu adevărat diferite în construirea API-urilor. Dacă subiectul acesta vă interesează, Google în jurul „modelelor de design API” și „paradigme API”. Sau începeți pur și simplu cu acest articol corect la nivel de intrare. :)

Endpoints

Scopul API-urilor este de a vă ușura viața de dezvoltator. Cum fac asta?

Prin agregarea funcțiilor / funcțiilor setate și expunerea acestor funcționalități prin puncte finale. Acestea sunt de obicei modele URL utilizate pentru a comunica cu API-ul.

Aceste obiective sunt singurele moduri în care poți interacționa cu orice API. Fiecare punct final va avea un format specificat atât pentru cererile sale cât și pentru răspunsurile sale. De obicei, veți găsi acest format definit în documentația API.

Obiectivele finale pot fi funcții simple. Sau pot fi compuse din mai multe funcții, care pot apela alte API-uri și așa mai departe.

Punctul crucial aici este faptul că logica care stă la baza acestor funcții este complet abstractizată. Nu aveți nevoie de cunoștințe despre ceea ce se întâmplă în interiorul lor pentru a le utiliza.

Atâta timp cât folosiți formatul corespunzător, veți putea să le consumati. Aici, „consuma” este un mod fantezist de a spune „folosind părți din ele pentru aplicația ta”.

Linia de jos este aceasta: o API este la fel ca orice interfață.

Ca o comparație, un comutator de lumină va aprinde o lumină, indiferent dacă funcționează sau nu curenții electrici. (În vârstă tânără, am învățat, de asemenea, că trebuie să plătiți factura la electricitate pentru ca aceasta să funcționeze ... dar aceasta este o altă poveste ...)

Cum se utilizează API-urile: exemple practice

Haideți să schimbăm teoria pentru câteva practici ușoare acum.

Citirea documentației API

Nu vreau să exagerez prea mult explicațiile conceptuale. În schimb, să analizăm o API cu adevărat simplă. Vom vedea cum funcționează într-un scenariu din viața reală. Vom folosi obiectul nativ JavaScript Math pentru a face acest lucru. Puteți citi documentația ei aici.

Documentele explică modul în care fiecare funcție a obiectului Math descrie care ar trebui să fie formatul de intrare. De exemplu, ar putea fi un număr sau o serie de numere.

Documentele descriu, de asemenea, formatul de ieșire.

Observați cum nu este menționat nimic despre logica folosită pentru a rula aceste funcții.

De exemplu, dacă porniți consola browserului și tastați Math.sqrt (fără a executa funcția), veți vedea ceva de genul:

ƒ sqrt () {[cod nativ]}

Acesta este spiritul unei API. Fie că apelați una dintre API-urile sistemului de operare sau o API bazată pe web, aceste principii vor rămâne.

Exemple de bază de cazuri de utilizare API

Există o mulțime de lucruri care pot fi realizate cu furnizori de API populari acolo.

API-ul Google Maps este adesea folosit pentru a crea experiențe mai bune ale utilizatorilor cu date bazate pe cartografiere în timp real și semnale de trafic. API-ul Twitter poate fi utilizat pentru a filtra și a afișa Tweeturi vizate în timp real.

Acum, bănuiesc că mulți dintre voi sunt mai interesați de API-urile web decât de orice altceva. Deci, să ne scufundăm în cazuri specifice de utilizare.

Vom folosi Postman în exemplele noastre. Acest Client de odihnă este legat de un mediu web, dar aceste instrumente există de obicei și în alte medii. Merită să aruncați o privire în jurul instrumentelor furnizate pentru un mediu dat înainte de a începe să vă jucați cu ele. Acest lucru vă poate economisi mult timp.

Dacă doriți să urmați mai departe, va trebui să descărcați clientul Postman.

Consumarea unei API publice pentru a prelua date

Primul nostru exemplu va fi destul de simplu, dar totuși mai interesant decât cel matematic.

Vom folosi API-ul Dog!

Nu numai că este o API amuzantă, dar, de asemenea, nu necesită nicio autentificare.

În plus, este o API-ul HTTP REST. Aceasta înseamnă că este o API bazată pe web. Întrucât este legat de acest mediu, ne solicită să ne conformăm la o parte din specificul protocolului.

În acest caz, aceasta înseamnă utilizarea verbelor HTTP precum GET, PUT, POST, DELETE.

De exemplu, vom păstra lucrurile simple și vom folosi doar verbul GET. API-ul nu acceptă nimic altceva. Majoritatea API-urilor publice vă permit să consumați date și să nu postați niciuna.

Aruncăm funcția Postman și vedem cum arată UI-ul.

Interfața de utilizare utilizează tema întunecată, deci ar putea diferi ușor de a ta.

S-ar putea să fi digerat mai multe informații la început aici, așa că să începem doar cu VERB și URL.

Verbul implicit ar trebui să fie GET. Dacă da, îl puteți păstra în acest fel și introduceți următoarea adresă URL: https://dog.ceo/api/breeds/list/all

Apăsați „Trimiteți” și bateți! Ar trebui să primiți un răspuns cu datele corespunzătoare. Voilà! Tocmai ați făcut primul dvs. apel API.

Acum, de exemplu, nu vom folosi niciuna dintre datele primite. Dar ți-ai făcut ideea. Puteți arăta utilizatorilor dvs. diferite rase de câini și puteți afișa o imagine a unei rase date dacă faceți clic pe ea.

Vă puteți juca cu diferitele rute din documentația lor pentru a vă familiariza cu mediul înconjurător.

Fapt misto: acest mic proiect este de asemenea open source, așa că puteți arunca o privire sub capotă aici.

Gestionarea autentificării cu o API privată

Sperăm că acum înțelegeți mai bine modul în care diferite piese lucrează împreună când vine vorba de API-uri. Să facem un tutorial mai complex care include autentificarea. Voi folosi aici una dintre API-urile mele „proprii”.

Aici vom folosi doar codul pentru a interacționa cu API-ul Snipcart. Puteți închide Postman, dar păstrați-l la îndemână. Este bine să folosiți un astfel de instrument atunci când începeți cu o API.

Scopul va fi crearea unui instrument de interfață de linie de comandă simplă (CLI) pentru a crea reduceri de utilizare de 1 dată pentru cumpărători. Aceste reduceri vor fi generate prin intermediul unei API. Toate acestea se vor întâmpla în întregime pe computer.

Creați un nou folder pentru acest proiect. Folosiți npm init în folder și porniți editorul de text.

Acum creați un fișier index.js, apoi deschideți package.jsonfile. În el, adăugați următoarele linii în obiectul de nivel superior:

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

De asemenea, vom avea nevoie de pachetul de comandă pentru a analiza intrările de la client. Rulați npm install --save comandant în folderul curent.

De asemenea, vom folosi un mic lib pentru a crea ID-uri. Puteți să-l instalați cu npm install - salvare shortid.

În timp ce ne aflăm la el, să rulăm și npm instalare - cerere salvare lib. Acest lucru ne va facilita apelurile HTTP. Salt în fișierul index.js și lipiți acest cod:

Să ne concentrăm doar pe funcția de solicitare aici.

Aici facem apelul API extern către Snipcart. Puteți vedea că trecem metoda: „POST” la metodă. Acest lucru se datorează faptului că dorim să POSTăm datele în API-ul Snipcart. Prin specificarea acestei metode, API-ul va cartografia acțiunea corect. Acest lucru îi permite să citească corpul cererii în care se află datele de reducere.

O caracteristică API interesantă pe care nu am folosit-o încă este autentificarea.

Celelalte exemple noastre au fost toate pe API-urile publice. Acestea nu necesită autentificare.

Dar, în viața reală, majoritatea API-urilor pe care le veți folosi vor necesita probabil o anumită autentificare. Este un „model” standard în lumea API. Clienții noștri nu ar fi mulțumiți dacă am permite oricui să creeze reduceri la magazinul său! ;)

În scopul nostru, trecem cheia API direct în cerere.

Hooray - serverul ne recunoaște! Apoi poate executa cererea orientată numai către contul nostru.

Dacă doriți să testați mica noastră aplicație, puteți rula npm install -g în directorul de proiect. Apoi, pur și simplu executați reduceri x pentru a crea reduceri x număr de ori.

Puteți accesa tabloul de bord Snipcart (conturi pentru totdeauna gratuite în modul Test) și puteți vedea pentru dvs. că reducerile au fost create corect.

Vă puteți imagina cât de puternic poate fi acest lucru. Dacă ar trebui să creezi 200 din aceste reduceri, acest lucru ar necesita prea mult timp pentru a face acest lucru prin interfața de utilizator.

Dacă vă familiarizați cu modul în care funcționează API-urile, acest lucru se poate face în câteva minute. Codul este, de asemenea, reutilizabil, așa că dacă trebuie să faceți același lucru pe o lună de acum, ei bine ... ești deja setat!

Gânduri de închidere

Sper cu adevărat că acest primer te-a ajutat să înțelegi mai bine ce sunt API-urile și cum le poți folosi în fluxul de lucru pentru dezvoltare.

Câteva oferte:

  • API-urile vă vor accelera viteza și vă vor lărgi domeniul de dezvoltare. Utilizati-le!
  • API-urile NU sunt obligatoriu legate de ecosistemul web. Le veți vedea peste tot.
  • Verificați întotdeauna documentația API-ului pe care doriți să o utilizați.
  • Căutați întotdeauna instrumentele existente (API-uri sau altfel) în ecosistemul dvs. înainte de a începe codul.

Ultimul nostru exemplu nu este pregătit pentru „producție”. Dar vă oferă o idee bună despre cum ar putea arăta lucrurile într-un caz de utilizare reală.

Sunt multe lucruri pe care le-am fi putut îmbunătăți. De exemplu:

  • Permitând utilizatorului să aleagă tipul de reducere
  • De asemenea, am putea trimite codurile create prin e-mail direct în aceeași funcție, în loc să le înregistrăm pur și simplu.
  • Dacă am fi avut nevoi avansate pentru instrumentele noastre de reduceri, am fi putut scrie singuri o API. De acolo, am putea chiar să creăm o IU care să interacționeze cu API-ul nostru dacă am dori. Oricum, sper că veți primi ideea acum.! :)

Care este următorul pas? Ca aproape orice în domeniul dezvoltării, va trebui să codați, să codați, să codați și să codați încă ceva! Așa vă veți familiariza cu gestionarea și integrarea API.

După un timp, vei deveni eficient cu ei.

Și de aici începe adevărata distracție.

Dacă v-a plăcut această postare, luați o secundă pentru a aplauda și a o distribui pe Twitter. Aveți comentarii, întrebări? Atingeți secțiunea de mai jos!

Am publicat inițial acest lucru pe blogul Snipcart și l-am împărtășit în newsletter-ul nostru.