Înțelegerea și utilizarea API-urilor REST

Există șanse mari să întâlniți termenul „REST API” dacă v-ați gândit să obțineți date dintr-o altă sursă de pe internet, cum ar fi Twitter sau Github. Dar ce este un API REST? Ce poate face pentru tine? Cum o utilizați?

În acest articol, veți afla tot ce trebuie să știți despre API-urile REST pentru a putea citi documentațiile API și a le utiliza eficient.

Ce este un API REST

Să presupunem că încerci să găsești videoclipuri despre Batman pe Youtube. Deschideți Youtube, introduceți „Batman” într-un câmp de căutare, apăsați Enter și vedeți o listă de videoclipuri despre Batman. O API REST funcționează într-un mod similar. Căutați ceva și primiți o listă de rezultate din serviciul de la care solicitați.

Un API este o interfață de programare a aplicațiilor. Este un set de reguli care permit programelor să vorbească între ele. Dezvoltatorul creează API-ul pe server și permite clientului să vorbească cu acesta.

REST determină cum arată API-ul. Aceasta înseamnă „Transfer de stat reprezentativ”. Este un set de reguli pe care dezvoltatorii le urmează atunci când își creează API-ul. Una dintre aceste reguli prevede că ar trebui să puteți obține o parte de date (numită resursă) atunci când vă conectați la o anumită adresă URL.

Fiecare adresă URL este numită cerere , în timp ce datele trimise înapoi se numesc răspuns .

Anatomia unei cereri

Este important să știți că o cerere este alcătuită din patru lucruri:

1. Punctul final
2. Metoda
3. Antetele
4. Datele (sau corpul)

Punctul final (sau ruta) este adresa URL pe care o solicitați. Urmează această structură:

 root-endpoint/ ? root-endpoint/ ? root-endpoint/ ?

Punctul final rădăcină este punctul de pornire al API-ului de la care solicitați. Punctul final rădăcină al API-ului Github este https://api.github.com , în timp ce API-ul Twitter al punctului final rădăcină este https://api.twitter.com .

Calea determină resursa pentru care solicitați. Gândiți-vă la el ca la un robot telefonic automat care vă cere să apăsați 1 pentru un serviciu, apăsați 2 pentru un alt serviciu, 3 pentru încă un serviciu și așa mai departe.

Puteți accesa căi la fel cum puteți face linkuri către părți ale unui site web. De exemplu, pentru a obține o listă cu toate postările etichetate sub „JavaScript” pe Smashing Magazine, navigați la https://www.smashingmagazine.com/tag/javascript/ . https://www.smashingmagazine.com/ este punctul final de rădăcină și /tag/javascript este calea.

Pentru a înțelege ce căi vă sunt disponibile, trebuie să vă uitați prin documentația API. De exemplu, să presupunem că doriți să obțineți o listă de depozite de către un anumit utilizator prin API-ul Github. Documentele vă spun să utilizați următoarea cale pentru a face acest lucru:

 /users/:username/repos

Orice două puncte ( : ) de pe o cale denotă o variabilă. Ar trebui să înlocuiți aceste valori cu valorile reale ale când trimiteți solicitarea. În acest caz, ar trebui să înlocuiți :username cu numele de utilizator real al utilizatorului pe care îl căutați. Dacă îmi caut contul Github, voi înlocui :username cu zellwk .

Punctul final pentru a obține o listă a depozitelor mele pe Github este acesta:

 https://api.github.com/users/zellwk/repos

Partea finală a unui punct final o reprezintă parametrii de interogare . Din punct de vedere tehnic, parametrii de interogare nu fac parte din arhitectura REST, dar veți vedea că multe API-uri îi folosesc. Deci, pentru a vă ajuta să înțelegeți complet cum să citiți și să utilizați API-urile, vom vorbi și despre ele. Parametrii de interogare vă oferă opțiunea de a modifica solicitarea cu perechi cheie-valoare. Ele încep întotdeauna cu un semn de întrebare ( ? ). Fiecare pereche de parametri este apoi separată cu un ampersand ( & ), astfel:

 ?query1=value1&query2=value2

Când încercați să obțineți o listă a depozitelor unui utilizator pe Github, adăugați trei parametri posibili la cererea dvs. de modificare a rezultatelor care vi se oferă:

Dacă doriți să obțineți o listă a depozitelor în care am trimis recent, puteți seta sort la push .

 https://api.github.com/users/zellwk/repos?sort=pushed

Cum știi dacă acest punct final funcționează? Ei bine, este timpul să încerci!

Testarea punctelor finale cu curl

Puteți trimite o solicitare cu orice limbaj de programare. Utilizatorii JavaScript pot folosi metode precum API-ul Fetch și metoda Ajax a jQuery; Utilizatorii Ruby pot folosi clasa Ruby's Net::HTTP, utilizatorii Python pot folosi Cereri Python; și așa mai departe.

Pentru acest articol, vom folosi utilitarul de linie de comandă numit cURL. Folosim cURL deoarece documentațiile API sunt scrise în mod normal cu referire la cURL. Dacă înțelegeți cum să utilizați cURL, nu veți avea probleme în înțelegerea documentațiilor API. Apoi, puteți efectua cu ușurință cereri în limba preferată.

Înainte de a continua, veți dori să vă asigurați că aveți cURL instalat pe computer. Deschideți terminalul și tastați curl -version . Această comandă verifică versiunea de cURL pe care ați instalat-o pe sistemul dumneavoastră.

 curl --version

Dacă nu aveți instalat cURL, veți primi o eroare „comandă nu a fost găsită”. Dacă primiți această eroare, va trebui să instalați curl înainte de a continua.

Pentru a utiliza cURL, tastați curl , urmat de punctul final pentru care solicitați. De exemplu, pentru a obține punctul final rădăcină Github, tastați următoarele:

 curl https://api.github.com

Odată ce apăsați enter, ar trebui să primiți un răspuns de la Github care arată astfel:

Pentru a obține o listă a depozitelor unui utilizator, modificați punctul final la calea corectă, așa cum am discutat mai sus. Pentru a obține o listă a depozitelor mele, puteți folosi această comandă:

 curl https://api.github.com/users/zellwk/repos

Dacă doriți să includeți parametrii de interogare cu cURL, asigurați-vă că adăugați o bară oblică inversă ( \ ) înainte de ? și = caractere. Aceasta pentru că ? și = sunt caractere speciale în linia de comandă. Trebuie să folosiți \ înaintea lor pentru linia de comandă pentru a le interpreta ca caractere normale:

 curl https://api.github.com/users/zellwk/repos\?sort\=pushed

Încercați să utilizați oricare dintre comenzi și efectuați o solicitare! Veți obține un răspuns similar cu ceea ce ați văzut cu root-endpont-ul Github (dar cu mult mai multe date).

JSON

JSON (JavaScript Object Notation) un format comun pentru trimiterea și solicitarea datelor printr-un API REST. Răspunsul pe care Github ți-l trimite înapoi este, de asemenea, formatat ca JSON.

Un obiect JSON arată ca un obiect JavaScript. În JSON, fiecare proprietate și valoare trebuie să fie înfășurată cu ghilimele duble, astfel:

 { "property1": "value1", "property2": "value2", "property3": "value3" }

Înapoi la anatomia unei cereri

Ați învățat că o solicitare constă din patru părți.

1. Punctul final
2. Metoda
3. Antetele
4. Datele (sau corpul)

Să trecem prin restul a ceea ce alcătuiește o cerere.

Metoda

Metoda este tipul de solicitare pe care o trimiteți către server. Puteți alege dintre aceste cinci tipuri de mai jos:

• GET
• POST
• PUT
• PATCH
• DELETE

Aceste metode oferă sens pentru cererea pe care o faceți. Acestea sunt folosite pentru a efectua patru acțiuni posibile: Create , Read , Update și Delete (CRUD).

API-ul vă permite să știți ce metodă de solicitare să utilizați fiecare cerere. De exemplu, pentru a obține o listă a depozitelor unui utilizator, aveți nevoie de o solicitare GET :

Este necesară o solicitare GET pentru a obține o listă de depozite de la un utilizator. Pentru a crea un nou depozit Github, aveți nevoie de o solicitare POST :

Puteți seta metoda de solicitare în cURL scriind -X sau --request , urmat de metoda de solicitare. Această comandă de mai jos încearcă să creeze un depozit prin cURL:

 curl -X POST https://api.github.com/user/repos

Încercați să rulați această solicitare. Veți primi un răspuns care vă spune că este necesară autentificarea. (Mai multe despre autentificare mai târziu).

 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

Anteturile

Anteturile sunt folosite pentru a furniza informații atât clientului, cât și serverului. Poate fi folosit în multe scopuri, cum ar fi autentificarea și furnizarea de informații despre conținutul corpului. Puteți găsi o listă de anteturi valide în Referința antetelor HTTP de la MDN.

Antetele HTTP sunt perechi proprietate-valoare care sunt separate prin două puncte. Exemplul de mai jos arată un antet care îi spune serverului să aștepte conținut JSON.

 "Content-Type: application/json". Missing the opening ".

Puteți trimite anteturi HTTP cu curl prin opțiunea -H sau --header . Pentru a trimite antetul de mai sus la API-ul Github, utilizați această comandă:

 curl -H "Content-Type: application/json" https://api.github.com

(Notă: antetul Content-Type nu este o cerință pentru ca API-ul Github să funcționeze. Acesta este doar un exemplu pentru a ilustra cum să utilizați un antet cu cURL).

Pentru a vedea anteturile pe care le-ați trimis, puteți utiliza opțiunea -v sau --verbose pe măsură ce trimiteți solicitarea, astfel:

 curl -H "Content-Type: application/json" https://api.github.com -v 

Aici, * se referă la informații suplimentare furnizate de cURL. > se referă la anteturile cererii, iar < se referă la anteturile răspunsului.

Datele (sau „corpul”)

Datele (numite uneori „corp” sau „mesaj”) conțin informații pe care doriți să le trimiteți serverului. Această opțiune este utilizată numai cu solicitările POST , PUT , PATCH sau DELETE .

Pentru a trimite date prin cURL, puteți utiliza opțiunea -d sau --data :

 curl -X POST <URL> -d property1=value1

Pentru a trimite mai multe câmpuri de date, puteți crea mai multe opțiuni -d :

 curl -X POST <URL> -d property1=value1 -d property2=value2

Dacă are sens, puteți împărți solicitarea în mai multe rânduri \ pentru a fi mai ușor de citit:

 curl -X POST <URL> \ -d property1=value1 \ -d property2=value2

Dacă știi cum să pornești un server, poți să creezi un API și să-ți testezi propriile date. Dacă nu știți, dar vă simțiți suficient de curajos pentru a încerca, puteți urma acest articol pentru a învăța să creați un server cu Node, Express și MongoDB

Dacă nu doriți să vă învârtiți serverul, puteți accesa Requestbin.com ( este gratuit! ) și faceți clic pe „creați punctul final”. Vi se va oferi o adresă URL pe care o puteți utiliza pentru a testa solicitările, cum ar fi https://requestb.in/1ix963n1 prezentat în imaginea de mai jos.

Asigurați-vă că vă creați propriul coș de cereri dacă doriți să vă testați cererea. Coșurile de solicitare rămân deschise doar 48 de ore de la crearea sa. Până când veți citi acest articol, coșul pe care l-am creat mai sus va fi dispărut de mult.

Acum, încercați să trimiteți câteva date în coșul de solicitare, apoi reîmprospătați pagina web a coșului. Veți vedea câteva date, precum aceasta:

 curl -X POST https://requestb.in/1ix963n1 \ -d property1=value1 \ -d property2=value2 

În mod implicit, cURL trimite date ca și cum ar fi trimise prin „câmpuri de formular” pe o pagină. Dacă doriți să trimiteți date JSON, va trebui să setați Content-Type la application/json și va trebui să formatați datele ca obiect JSON, astfel:

 curl -X POST https://requestb.in/1ix963n1 \ -H "Content-Type: application/json" \ -d '{ "property1":"value1", "property2":"value2" }' 

Și asta este (aproape!) tot ce trebuie să știi despre structura unei cereri.

Acum, țineți minte când ați încercat să trimiteți o solicitare POST prin API-ul Github, ați primit un mesaj care spune „Necesită autentificare”? Ei bine, asta pentru că nu sunteți autorizat să efectuați cererea POST !

Autentificare

Nu ați permite nimănui să vă acceseze contul bancar fără permisiunea dvs., nu-i așa? Pe aceeași linie de gândire, dezvoltatorii pun măsuri pentru a se asigura că efectuați acțiuni numai atunci când sunteți autorizat să faceți. Acest lucru îi împiedică pe ceilalți să se uzurpe la tine.

Deoarece cererile POST , PUT , PATCH și DELETE modifică baza de date, dezvoltatorii le pun aproape întotdeauna în spatele unui zid de autentificare. În unele cazuri, o solicitare GET necesită, de asemenea, autentificare (cum ar fi atunci când accesați contul bancar pentru a vă verifica soldul curent, de exemplu).

Pe web, există două moduri principale de a vă autentifica:

1. Cu un nume de utilizator și o parolă (numită și autentificare de bază)
2. Cu un simbol secret

Metoda simbolului secret include oAuth, care vă permite să vă autentificați cu rețelele de social media precum Github, Google, Twitter, Facebook etc.

Pentru acest articol, veți învăța să utilizați autentificarea de bază doar cu un nume de utilizator și o parolă. Dacă sunteți interesat să vă autentificați cu oAuth, vă sugerez să citiți „Ce trebuie să știți despre OAuth2 și conectarea cu Facebook” de Zack Grossbart.

Pentru a efectua o autentificare de bază cu cURL, puteți utiliza opțiunea -u , urmată de numele de utilizator și parola, astfel:

 curl -x POST -u "username:password" https://api.github.com/user/repos

Încercați să vă autentificați cu numele de utilizator și parola în solicitarea de mai sus. Odată ce reușiți autentificarea, veți vedea că răspunsul se schimbă din „Necesită autentificare” în „Probleme la analizarea JSON”.

Acest lucru se datorează faptului că încă nu ați furnizat date (care sunt cerute de toate solicitările POST , PUT , PATCH și DELETE ) către server.

Cu cunoștințele pe care le-ați învățat până acum, ar trebui să puteți edita codul de mai sus pentru a crea un depozit Github prin intermediul cURL-ului dvs. Te las pe tine sa incerci tu!

Acum, să vorbim despre codurile de stare HTTP și despre mesajele de eroare.

Codurile de stare HTTP și mesajele de eroare

Unele dintre mesajele pe care le-ați primit mai devreme, cum ar fi „Necesită autentificare” și „Probleme la analizarea JSON” sunt mesaje de eroare. Acestea apar doar atunci când ceva nu este în regulă cu solicitarea dvs. Codurile de stare HTTP vă permit să spuneți rapid starea răspunsului. Gama de la 100+ la 500+. În general, numerele respectă următoarele reguli:

1. 200+ înseamnă că solicitarea a reușit .
2. 300+ înseamnă că solicitarea este redirecționată către o altă adresă URL
3. 400+ înseamnă că a apărut o eroare care provine de la client
4. 500+ înseamnă că a apărut o eroare care provine de la server

Puteți depana starea unui răspuns cu opțiunea verbose ( -v sau --verbose ) sau opțiunea head ( -I sau --head ).

De exemplu, dacă ați încercat să adăugați -I la o solicitare POST fără a furniza numele de utilizator și parola, veți primi un cod de stare 401 (Neautorizat):

Dacă solicitarea dvs. este nevalidă deoarece datele dvs. sunt greșite sau lipsesc, de obicei primiți un cod de stare 400 (Solicitare greșită).

Pentru a obține mai multe informații despre anumite coduri de stare HTTP, poate doriți să consultați Referința privind starea HTTP de la MDN.

Versiuni API

Dezvoltatorii își actualizează API-urile din când în când. Uneori, API-ul se poate schimba atât de mult încât dezvoltatorul decide să-și actualizeze API-ul la o altă versiune. Dacă se întâmplă acest lucru și aplicația dvs. se întrerupe, de obicei este pentru că ați scris cod pentru un API mai vechi, dar solicitarea dvs. indică API-ul mai nou.

Puteți solicita o anumită versiune API în două moduri. Modul în care alegeți depinde de modul în care este scris API-ul.

Aceste două moduri sunt:

1. Direct în punctul final
2. Într-un antet de solicitare

Twitter, de exemplu, folosește prima metodă. La momentul scrierii, API-ul Twitter se află la versiunea 1.1, ceea ce este evident prin punctul final:

 https://api.twitter.com/1.1/account/settings.json

Github, pe de altă parte, folosește a doua metodă. La momentul scrierii, API-ul Github este la versiunea 3 și puteți specifica versiunea cu un antet Accept :

 curl https://api.github.com -H Accept:application/vnd.github.v3+json

Încheierea

În acest articol, ați învățat ce este un API REST și cum să utilizați cURL pentru a efectua o solicitare cu metodele GET , POST , PUT , PATCH și DELETE . În plus, ați învățat și cum să vă autentificați cererile cu opțiunea -u și ce înseamnă stările HTTP.

Sper că acest articol v-a ajutat să învățați suficient despre API-urile REST și să le puteți folosi fluent pe măsură ce vă creați aplicațiile. Simțiți-vă liber să accesați blogul meu sau să lăsați comentariile voastre mai jos dacă aveți întrebări.