Share
Dacă ați petrecut ceva timp cu dezvoltarea web modernă, veți fi întâlnit termeni precum REST și API. Dacă ați auzit de acești termeni sau ați lucrat cu API-uri, dar nu aveți o înțelegere completă a modului în care funcționează sau cum să vă creați propriul API, această serie este pentru dvs..
În această serie de tutori, vom începe cu o prezentare generală a principiilor și conceptelor REST. Apoi, vom continua să creăm propriul API complet, care rulează pe un server Express Node.js și se conectează la o bază de date MySQL. După terminarea acestei serii, trebuie să vă simțiți încrezători în construirea propriului API sau în explorarea documentației unui API existent.
Pentru a profita la maximum de acest tutorial, trebuie să aveți deja câteva cunoștințe de bază de linie de comandă, să cunoașteți fundamentele JavaScript și să instalați Node.js la nivel global.
Transferul de stat reprezentativ sau ODIHNĂ, descrie un stil arhitectural pentru serviciile web. REST constă într-un set de standarde sau constrângeri pentru partajarea datelor între diferite sisteme, iar sistemele care implementează REST sunt cunoscute ca RESTful. REST este un concept abstract, nu un limbaj, cadru sau tip de software.
O analogie liberă pentru REST ar fi păstrarea unei colecții de vinil vs. folosirea unui serviciu de redare muzicală. Cu colecția fizică de vinil, fiecare înregistrare trebuie să fie duplicată în întregime pentru a partaja și distribui copii. Cu un serviciu de streaming, cu toate acestea, aceeași muzică poate fi partajată în permanență printr-o referire la unele date, cum ar fi un titlu de melodie. În acest caz, muzica streaming este un serviciu RESTful, iar colecția de vinil este un serviciu non-RESTful.
Un API-ul este o interfață de programare a aplicațiilor, care este o interfață care permite programelor software să comunice între ele. A RESTful API este pur și simplu un API care aderă la principiile și constrângerile REST. Într-un API Web, un server primește a cerere printr-un punct final URL și trimite un a raspuns în schimb, care este adesea date într-un format cum ar fi JSON.
Șase constrângeri de ghidare definesc arhitectura REST, prezentate mai jos.
Veți fi deja familiarizat cu faptul că toate site-urile au URL-uri care încep cu http (sau https pentru versiunea securizată). Protocol de transfer HyperText, sau HTTP, este metoda de comunicare între clienți și servere pe internet.
Vedem cel mai evident în bara de adrese URL a browserelor noastre, dar HTTP poate fi folosit pentru mai mult decât să solicite site-uri de pe servere. Când te duci la o adresă URL pe web, faci de fapt a OBȚINE solicitați această resursă specifică, iar site-ul pe care îl vedeți este corpul răspunsului. Vom merge peste OBȚINE și alte tipuri de solicitări în scurt timp.
HTTP funcționează prin deschiderea unui TCP (Transmission Control Protocol) la un port server (80 pentru http, 443 pentru https) pentru a face o cerere, iar serverul de ascultare răspunde cu o stare și un corp.
O solicitare trebuie să conțină o adresă URL, o metodă, informații antet și un corp.
Există patru metode importante HTTP, denumite și verbe HTTP, care sunt utilizate în mod obișnuit pentru a interacționa cu API-urile Web. Aceste metode definesc acțiunea care va fi efectuată cu orice resursă dată.
Metodele de solicitare HTTP corespund liber paradigmei CRUD, care înseamnă Creați, actualizați, citiți, ștergeți. Deși CRUD se referă la funcțiile utilizate în operațiile bazei de date, putem aplica aceste principii de proiectare verbelor HTTP într-un API RESTful.
| Acțiune | Metoda de solicitare | Definiție |
|---|---|---|
| Citit | OBȚINE | Preia o resursă |
| Crea | POST | Creează o nouă resursă |
| Actualizați | A PUNE | Actualizează o resursă existentă |
| Șterge | ȘTERGE | Șterge o resursă |
OBȚINE este o operațiune sigură, numai pentru citire, care nu va modifica starea unui server. De fiecare dată când atingeți o adresă URL în browserul dvs., cum ar fi https://www.google.com, trimiteți a OBȚINE solicitați serverelor Google.
POST este folosit pentru a crea o nouă resursă. Un exemplu familiar de POST se înscrie ca utilizator pe un site sau o aplicație. După trimiterea formularului, a POST cererea cu datele utilizatorului poate fi trimisă către server, care apoi va scrie acele informații într-o bază de date.
A PUNE actualizează o resursă existentă, care ar putea fi utilizată pentru a edita setările unui utilizator existent. Spre deosebire de POST, A PUNE este idempotente, adică același apel poate fi făcut de mai multe ori fără a produce un rezultat diferit. De exemplu, dacă ați trimis același lucru POST să creeze un utilizator nou într-o bază de date de mai multe ori, ar crea un utilizator nou cu aceleași date pentru fiecare solicitare pe care ați făcut-o. Cu toate acestea, folosind același lucru A PUNE solicitarea aceluiași utilizator ar produce în mod constant același rezultat.
ȘTERGE, după cum sugerează și numele, va șterge pur și simplu o resursă existentă.
Odată ce o solicitare trece de la client la server, serverul va trimite înapoi un răspuns HTTP, care va include metadate despre răspunsul cunoscut ca anteturi, precum și despre organism. Prima și cea mai importantă parte a răspunsului este codul de stare, care indică dacă o solicitare a avut succes, dacă a apărut o eroare sau dacă trebuie întreprinsă o altă acțiune.
Cel mai bine-cunoscut cod de răspuns va fi familiarizat cu este 404, care înseamnă Nu a fost gasit. 404 face parte din 4xx clasa de coduri de stare, care indică erorile clientului. Există cinci clase de coduri de stare care conțin fiecare o serie de răspunsuri.
Accentsconagua
1xx: Informație2xx: Succesul3xx: Redirecționare4xx: Eroare de client5xx: Eroare de serverAlte răspunsuri comune cu care vă puteți familiariza sunt 301 mutat permanent, care este folosit pentru a redirecționa site-uri web la noi adrese URL, și 500 Eroare internă a server-ului, care este o eroare care apare frecvent când sa întâmplat ceva neașteptat pe un server care face imposibilă îndeplinirea cererii intenționate.
În ceea ce privește API-urile RESTful și verbele lor HTTP corespunzătoare, toate răspunsurile ar trebui să fie în 2xx gamă.
| Cerere | Raspuns |
|---|---|
OBȚINE | 200 (O.K) |
POST | 201 (Creată) |
A PUNE | 200 (O.K) |
ȘTERGE | 200 (O.K), 202 (Acceptat), sau 204 (Fara continut) |
200 OK este răspunsul care indică faptul că o solicitare are succes. Este folosit ca răspuns la trimiterea unui mesaj OBȚINE sau A PUNE cerere. POST va returna a 201 Creat pentru a indica faptul că a fost creată o nouă resursă și ȘTERGE are câteva răspunsuri acceptabile, care indică faptul că fie cererea a fost acceptată (202) sau nu există conținut de returnat deoarece resursa nu mai există (204).
Putem testa codul de stare al unei solicitări de resurse folosind cURL, care este un instrument de linie de comandă utilizat pentru transferul de date prin adrese URL. Utilizarea răsuci, urmată de -eu sau --include pavilion, va trimite a OBȚINE solicitați o adresă URL și afișați anteturile și corpul. Putem testa acest lucru prin deschiderea programului de linie de comandă și testarea cURL cu Google.
curl -i https://www.google.com Google server va răspunde cu următoarele.
HTTP / 2 200 data: Tue, 14 Aug 2018 05:15:40 GMT expiră: -1 cache-control: private, max-age = 0 tip de conținut: text / html; charset = ISO-8859-1 ...
După cum vedem, răsuci cererea returnează mai multe antete și întregul corp HTML al răspunsului. Întrucât cererea a trecut cu succes, prima parte a răspunsului este 200 cod de stare, împreună cu versiunea HTTP (aceasta va fi fie HTTP / 1.1, fie HTTP / 2).
Întrucât această cerere specifică returnează un site web, site - ul tipul de conținut (Tipul MIME) care este returnat este text / html. Într-un API RESTful, probabil veți vedea application / json pentru a indica răspunsul este JSON.
Interesant este că putem vedea un alt tip de răspuns introducând o adresă URL puțin diferită. Fa a răsuci pe Google fără www.
curl -i https://google.com Adresă HTTP / 2 301: https://www.google.com/ type-type: text / html; charset = UTF-8
Redirecționările Google google.com la www.google.com, și utilizează a 301 răspuns pentru a indica faptul că resursa ar trebui redirecționată.
Atunci când un API este creat pe un server, datele pe care le conține sunt accesibile prin intermediul unor puncte finale. Un punct final este adresa URL a solicitării care poate accepta și procesa OBȚINE, POST, A PUNE, sau ȘTERGE cerere.
O adresă URL API va consta din șirul de interogare rădăcină, cale și șir de interogare opțional.
https://api.example.com sau https://api.example.com/v2: Rădăcina API, care poate consta în protocol, domeniu și versiune./ utilizatori /sau / utilizatorii / 5: Locația unică a resursei specifice.?locație = chicago & vârstă = 29: Perechi opționale de valoare cheie utilizate pentru sortare, filtrare și paginare.limită pentru a filtra răspunsurile numai pentru a include zece rezultate.https://api.example.com/users?limit=10
În general, atunci când utilizatorii se referă la un API ca API RESTful, aceștia se referă la convențiile de numire care intră în punctele finale de construire a adresei URL API. Câteva convenții importante pentru un API standard RESTful sunt următoarele:
5, am folosi / utilizatorii / 5, nu / User / 5..JSON.adăuga și șterge nu ar trebui să apară într-o adresă URL REST. Pentru a adăuga un utilizator nou, ați trimite pur și simplu a POST cererea de a / utilizatori, nu ceva de genul / utilizatori / adăugați. API-ul ar trebui să fie dezvoltat pentru a gestiona mai multe tipuri de solicitări către aceeași adresă URL.Toate aceste convenții sunt linii directoare, deoarece nu există standarde stricte REST pe care să le urmeze. Cu toate acestea, utilizarea acestor linii directoare va face ca API-ul dvs. să fie coerent, familiar și ușor de citit și de înțeles.
În acest articol, am aflat care sunt API-urile REST și RESTful, modul în care funcționează metodele de solicitare HTTP și codurile de răspuns, structura unei adrese URL API și convențiile comune API RESTful. În tutorialul următor, vom învăța cum să punem această teorie în aplicare prin crearea unui server Express cu Node.js și construirea propriului nostru API.
