Acum să începem în ordine.
REST (Transfer de stat reprezentativ).
REST (Transfer de stat reprezentativ).
Structura API-ului REST
1. Arhitectura client-server
2. Server fără stat
4. Structura cu mai multe straturi
5. Interfață unică
- Identificarea resurselor
- Interacțiunea cu resursele prin vizualizări
- Mesaje de sine stătătoare
- Hypermedia ca mecanism pentru gestionarea stărilor de aplicare (HATEOAS)
6. Cod la cerere (opțional)
Acum pentru fiecare element în detaliu.
Arhitectura, client - server. Separați logica aplicației de la clienți, faceți codul mai portabil, iar structura serverului este mai simplă și mai scalabilă. Dezvoltarea clienților și a serverului poate fi realizată complet independent.
Server fără stat - server. Starea clientului nu este stocată pe server, sub nici o formă, numai clientul este implicat în acest lucru. Acest lucru simplifică dezvoltarea și întreținerea serverului, făcându-l mai stabil.
Cacheable. Ar trebui dezvoltat un sistem clar de solicitări de cache la server, ceea ce permite îmbunătățirea semnificativă a performanței.
Structura cu mai multe straturi. Prezența / absența serverelor caching intermediare, echilibrarea încărcării, proxy-ul suplimentar trebuie să rămână complet neobservate de clienți.
Identificarea resurselor. Fiecare resursă are un URI unic (Uniform Resource Identifier). De exemplu:
În ceea ce privește ID-ul, sfătuiesc să mă uit la UUID (identificator unic universal), suportă majoritatea bazelor de date și această abordare va ajuta la asigurarea identității transversale a sistemelor de identificare. exemplu:
Mesaje de sine stătătoare. Fiecare răspuns trebuie să conțină toate informațiile necesare pentru ca acesta să poată fi procesat corect fără a recurge la ajutorul altor resurse.
HATEOAS. Hypermedia ca motor al statului de aplicare.
Hypermedia ca mecanism pentru gestionarea stărilor de aplicare.
Hypermedia este tipul de conținut al unei resurse cu activarea hipertextului. Hipertextul în acest context, conform lui Fielding, este prezentarea simultană a informațiilor și a elementelor de alegere.
"Astfel, hypermedia este doar o extensie, care se caracterizează prin prezența în conținutul conținutului de link-uri temporare la alt conținut din fluxul media".
Cod la cerere. Element opțional de structură. Vă permite să primiți codul programului pentru executarea ulterioară pe client.
Astfel, dacă cererea dvs. îndeplinește toate cerințele (restricțiile) descrise mai sus, aceasta poate fi denumită în siguranță RESTful. Singura excepție este codul la cerere - această opțiune este opțională.
Un API bun este ușor de înțeles și ușor de aplicat.
Elementele de bază ale REST prin HTTP.
O resursă este un obiect unic accesibil printr-o adresă URL unică.
Adresele URL principale trebuie să fie clare fără documentație.
acest lucru va contribui la simplificarea întreținerii API în viitor. O opțiune bună poate fi un prefix în numele domeniului:
Există două tipuri principale de resurse în arhitectura REST: colecția și elementul de colectare.
Colecția este un set de elemente independente și autosuficiente.
Exemplu de link către o colecție de utilizatori:
Un element al colecției utilizatorului sau un anumit utilizator în acest caz poate fi reprezentat ca:
Substantele sunt bune, verbele sunt rele.
Numele de colecții ar trebui să reprezinte entități (substantive în plural) și trebuie să fie cât mai specifice și mai ușor de înțeles (auto-documentare). Dacă e vorba de câini, atunci ar trebui să fie câini, nu doar animale.
Fiecare resursă din API-ul RESTful este controlată de mai multe verbe definite minimal necesare. În majoritatea cazurilor, există 4 verbe principale (metoda HTTP):
GET, PUT, DELETE sunt idempotent.
Idempotency înseamnă că, indiferent de câte ori numim o astfel de metodă, rezultatul va fi același.
Colecția de mașini a utilizatorului:
Este necesar să se distingă două familii principale de coduri de stare (codul de stare HTTP):
4xx - problema a apărut din partea utilizatorului și poate fi corectată prin introducerea corectă a informațiilor necesare interogării.
5xx - problema a apărut pe server și pentru ao rezolva, utilizatorul poate trimite o solicitare serviciului de asistență.
Erori ar trebui să fie descrise în mod clar, astfel încât nu numai utilizatorul să știe ce trebuie să facă, dar și navigarea ușoară dacă utilizatorul vă trimite o interogare pentru a rezolva problema.
Un exemplu de răspuns bine scris la o eroare:
Codul de stare HTTP: 401
Amintiți-vă! Scrieți API pentru aceiași dezvoltatori ca și dvs.
Utilizați starea minimă necesară de cod în aplicație.
Uneori poate fi 3:
2. 400 Solicitare incorectă (solicitare incorectă)
3. 500 Eroare internă de server (eroare de server intern)
Dacă nu este suficient, completați după cum este necesar:
1. 201 Creat (creat cu succes)
2. 304 Modificat (datele nu s-au schimbat)
3. 404 Nu a fost găsit (nu a fost găsit)
5. 403 interzis (acces refuzat)
Încercați să evaluați beneficiile fiecărui element pe care l-ați adăugat utilizatorului. Amintiți-vă că un număr mare, în special elemente inutile, poate deruta chiar dezvoltatori experimentați.
În unele cazuri, este util să aveți un parametru pentru a suprima starea codului de eroare, astfel încât clientul să poată primi întotdeauna codul 200, de exemplu, dacă este necesar.
Acest lucru va aduce o flexibilitate suplimentară API-ului dvs.
Versionare.
Asigurați-vă că specificați numărul versiunii, chiar dacă nu intenționați să modificați interfața - totul se poate schimba rapid.
sau în parametrii de interogare:
Nu are nici un rost să faci versiuni lungi ale versiunilor, inserând puncte în ele: v1.03
Expunerea paginată.
Orice colecție, indiferent cât de mică, în opinia dvs., nu ar trebui să fie dată pe o pagină de pagină. Definiți formatul colecției, de exemplu Content-Type: application / json, "paging":> Încercați să utilizați întotdeauna același format în toate răspunsurile la aplicații - faceți viața mai ușoară pentru dvs. și pentru dezvoltatorii software-ului client.
Merită alegerea unor valori implicite pentru parametrii "limit", "offset" și, cel mai probabil, pentru a limita valoarea maximă pentru "limită".
Ascundeți toate componentele complexe ale interogării pentru "?".
Dacă trebuie să utilizați filtre diferite în solicitarea dvs. GET - puneți-le în spatele semnului de întrebare (în parametrii URL):
Dați utilizatorului numai ceea ce dorește.
Permiteți clientului să primească numai acele câmpuri din cererea de care are nevoie:
Formatul datelor care trebuie trimise.
Nu vă limitați la niciun format. Efectuați un multiplu opțional, de exemplu, json și xml. În acest mod simplu, puteți simplifica în mod semnificativ dezvoltarea pentru clienți și nu va fi nevoie să selectați una. Formatul datelor returnate poate fi descris atât în antetele HTTP cât și în șirul de interogare:
Și merită să alegeți un format implicit.
Acesta este unul dintre puținele tipuri de resurse care sunt destinate să rămână un verb. Vreau să caut căutare globală.
Din nou, în funcție de sistemul folosit de motorul de căutare, puteți aplica diferite filtre.
Unele căutări locale, în cadrul colecției, pot fi realizate cu filtre simple:
Utilizați, dacă este posibil, ultima versiune de OAuth - OAuth 2.0 - acest sistem este bine cunoscut dezvoltatorilor și sa dovedit a fi bine. De ce să inventezi o bicicletă?
Documentația.
Acesta este unul dintre aspectele cele mai importante ale unui API bun. Oricine a întâlnit scrierea de script-uri client va fi de acord cu mine. Orele petrecute pe documentația bună vor fi mai mult decât să se plătească în lunile lungi ale biroului de asistență. Accentul este simplu - descrieți în mod concis și clar toate datele primite și livrate, precum și scopul metodelor. Amintiți-vă! Veți scrie pentru programatori. Nu descrieți niciun punct evident. Dați toate codurile de stare date; lista tuturor parametrilor acceptați îi descriu acolo unde este necesar; dați link-uri către materiale mai detaliate; dați exemple ale datelor obținute, dacă este cazul, cu descrierea acestora.
Încercați să oferiți în link-urile de răspunsuri toate resursele conexe, dacă doriți să respectați principiul HATEOAS și să vă numiți RESTful. Pentru aceasta veti fi foarte pasionat de dezvoltatorii de programe client - ei nu trebuie sa genereze aceste link-uri.
Acum, cel mai important lucru!
Fațadă pentru API.
Dezvoltarea oricărui API ar trebui să înceapă cu un studiu detaliat al interfeței. De fapt, la începutul scrierii codului pe mâini, trebuie să existe toate URI-urile API-ului cu documentație detaliată a tuturor parametrilor fiecărei metode disponibile pentru acest URI, cu toate codurile de stare returnate și formatele datelor returnate. În mod ideal, această interfață nu ar trebui să se schimbe în timpul dezvoltării ulterioare. Această abordare facilitează și accelerează foarte mult lucrul cu codul API principal și permite scrierea paralelă a software-ului client deja în primele etape de dezvoltare.
Amintiți-vă! Interfața API trebuie să fie cât mai simplă și mai simplă posibil, numai în acest fel puteți obține fericire și armonie.
Senior Web Developer / Team Lead, Grupul SECL / Tehnologii de vânzări pe Internet