Dacă ești Software Developer, e imposibil să nu fi auzit deja de conceptul de API sau REST API. Iar dacă încă nu-ți e foarte clar care-i treaba cu aceste APIs, la ce se folosesc ele și de ce toată lumea vorbește despre asta, ești la locul potrivit, pentru că în cele ce urmează o să-ți explic cât mai simplu posibil ce e acela un API cât și care-i treaba cu REST.
Ce este un API?
Bun și hai să începem prin a discuta despre ce e acela un API. Ei bine, "api" nu este un cuvânt care are o definiție anume în vreun dicționar, el este un acronim pentru: Application Programming Interface.
Ce trebuie să știi e că acest concept de "api" nu este tocmai nou și în ciuda faptului că vei auzi de el preponderent în zona de web, el există de foarte mult timp. Tipul de API de care vom discuta noi azi este un "Web API", care este defapt un serviciu web, care joacă rol de server pentru o aplicație de tip client (sau front-end, dacă vrei).
Așa cum spuneam, conceptul de API există de foarte mult timp, există de exemplu o multitudine de APIs în sistemul tău de operare, indiferent că folosești Windows, Linux sau MacOS.
Sistemele de operare expun diferite API-uri pe care aplicațiile le folosesc pentru a se "conecta" la sistem, pentru a interacționa cu el într-un fel sau altul.
Aceste APIs sunt un fel de conectori care expun diferite funcționalități gata dezvoltate, la care se pot conecta tot felul de aplicații, atâta timp cât se supun condițiilor API-ului respectiv, iar aici mă refer la parametri necesari pentru a apela metodele respective.
Hai să explorăm câteva exemple din viața reală pentru a înțelege mai bine.
Gândește-te că un API este ca un port USB, în care poți băga orice tip de device pentru a-l conecta. Apoi prin intermediul acelui USB ai posibilitatea fie doar să alimentezi device-ul, fie să faci transfer de date, fie amandouă în același timp.
Prin același port USB poți conecta un telefon mobil, de pe care să transferi date, sau poți de asemenea conecta un mouse sau o tastatură pe care să-l folosești ca periferic pentru sistemul tău.
Un alt exemplu potrivit ar fi telecomanda unui televizor.
Telecomanda este unealta, ca să-i spun așa, pe care televizorul o pune la dispoziție pentru a interacționa cu el sub o formă ușor de înțeles de către oameni. Noi ca și utilizatori nu știm care sunt procesele pe care electronica televizorului le execută intern în momentul în care noi apăsăm pe butoane și nici nu ne pasă de asta. Vrem doar un mod ușor prin care să schimbăm programele, să dam volumul mai tare sau mai încet, să oprim televizorul șamd.
Ce este REST? (RESTful)
REST este un acronim pentru "Representational State Transfer". Știu, sună cam complicat și nici nu știu cum aș putea să traduc asta în limba română.
"Transferul reprezentării stării"?
"Transferul reprezentativ al stării"?
E greu de spus.
REST este un tip de arhitectură care este folosit în dezvoltarea aplicațiilor web pentru backend, adică pentru partea de server. E defapt un set de principii pe care aplicația ta trebuie să le respecte pentru a fi o aplicație RESTful.
Termenul de REST (Representational State Transfer) a fost definit de Roy Fielding în teza lui de doctorat, susținută în anul 2000 la University of California.
Uite câteva criterii după care să te ghidezi dacă vrei să dezvolți un backend RESTful.
Arhitectură client-server
Unul dintre primele lucruri la care trebuie să avem grijă atunci când discutăm despre REST APIs, e acela că arhitectura soluției noastre să fie una client-server.
Adică să ai bine delimitată partea cu care interacționează utilizatorul (front-end) de server (back-end).
Ele trebuie să fie 2 sisteme absolut independente care să poată fi evoluate/schimbate fără a afecta funcționarea celuilalt.

Uniformizarea interfeței
Datele puse la dispoziție de către serverul tău sunt tratate sub formă de resurse independente, iar formatul răspunsului este unul de tip JSON sau în unele cazuri mai izolate, XML.
Convenția de denumire a câmpurilor returnate trebuie definită și respectată pentru a păstra congruența și unifromitatea interfeței publice.
De exemplu, dacă ai ales tipul de casing “camel”, atunci toate câmpurile tuturor resurselor, vor terbui definite astfel:
{
"employeeId": 1,
"firstName": "Lorem",
"lastName": "Ipsum",
"dateOfBirth": "04/11/2001"
"active": true
}
După cum observi, toate câmpurile respectă convenția “camel case”, unde încep cu literă mică și se folosesc litere mari ca separatori între cuvinte.
Reducerea cât mai mult posibil a redundanței datelor. Adică un set de date, cum ar fi în cazul de mai sus datele legate de un angajat (exceptând id-ul), ar trebui să se poată obține doar de la un singur “endpoint”.
Termenul de “endpoint” reprezintă un “punct apelabil” pentru o resursă anume.
- https://myapp/api/employees
- https://myapp/api/employees/1
Cele 2 URL-uri de mai sus reprezintă 2 “endpoints” diferite, de exemplu. Vorbim imediat și despre componentele acestor URL-uri și vei înțelege mai bine rolul fiecărei părți.
Lipsa stării (stateless)
Un RESTful API nu trebuie să dețină niciun fel de stare, ci să trateze fiecare request HTTP independent fără a face vreun fel de presupuneri.
Lucrul ăsta se obține prin a evita stocarea de informații legate de request-urile anterioare.
Toate informațiile necesare procesării unui request anume, trebuie să vină direct de la client(front-end), inclusiv elemente necesare autentificării & autorizării, astfel încât server-ul să poate fi absolut imparțial în ceea ce privește contextul execuției unui anume request.
Posibilitatea salvării datelor în cache
Oricare răspuns al server-ului ar trebui să poată fi adăugat într-o stocare temporară de tip “cache”, existând astfel posibilitatea de a reduce nivelul de încărcare (load) al serverului în cazuri cu request-uri repetitive ale căror date de răspuns nu se schimbă foarte des.
Ascunderea straturilor sistemului
REST permite stratificarea sau împărțirea server-ului principal în mai multe servere mai mici independente, dar cu respectarea primei condiții definite, aceea că interfața publică (structura datelor și convențiile folosite) să rămână neschimbată, indiferent câte straturi ale sistemului parcurge un request anume.
De asemenea, clientul, sau mai bine spus “consumatorul” acelui API, nu trebuie să știe absolut nimic de arhitectura internă și despre delegările pe care le face server-ul. Acestea sunt informații irelevante din punct de vedere al clientului, care trebuie să știe doar ce “endpoints” (puncte apelabile/de conexiune) să apeleze pentru a obține datele necesare în contextul respectiv.

Returnarea de cod executabil (opțional)
Nu e obligatoriu, dar un REST API poate returna și cod executabil clientului. În felul ăsta clientul poate îndeplini funcții care nu îi aparțin direct ci sunt implementate pe server.
E destul de comun ca aplicațiile web, de exemplu, să afișeze o fereastră al cărei cod provine de la server. În acest fel, se creează un fel de “capsulă” izolată prin care utilizatorul interacționează direct cu serverul.

Metode HTTP
Cele 4 metode cele mai folosite în aplicații de tip web API sunt: GET, POST, PUT, DELETE, care sunt și reprezentările acțiunilor de citire, creare, actualizare și ștergere. Acele operații de tip CRUD sau Create, Read, Update, Delete.
Sigur că mai sunt și alte metode HTTP în afară de acestea, dar în general acestea 4 sunt cele mai folosite.
Care este rolul acestor metode?
Exact de a transmite server-ului că facem un request de tip "citire", adică vrem să primim niște date, să creăm o nouă înregistrare, să actualizăm una deja existentă sau chiar s-o ștergem.
Avem nevoie să specificăm aceste metode, pentru că după cum vom vedea imediat, același URL poate fi folosit pentru a citi înregistrările sau a crea unele noi.
Structură URL
Uite câteva exemple de URL-uri ale unui posibil REST API:
- https://myapp/api/employees
- https://myapp/api/employees/1
- https://myapp/api/products
- https://myapp/api/products?category=food
Dacă ne uităm la primul URL, în funcție de metoda specificată, putem să obținem toți angajații existenți (dacă facem un GET) sau să creăm un nou angajat (dacă facem un POST).
Și-acum uitându-ne la structura URL-urilor, ne putem da seama pe viitor dacă aplicația pe care o folosim dispune de un server de tip REST.
Hai să vedem ce reprezintă fiecare din elementele unui URL.
Despre prima parte și anume protocolul HTTPS, nu cred că e cazul să mai discutăm, el funcționează la fel ca HTTP doar că informațiile transmise prin intermediul lui sunt criptate.
Am scris aici despre internele comunicării HTTPS.
"myapp" reprezintă domeniul aplicației respective, așa cum este "facebook.com" sau "youtube.com" și trebuie să fie unic. Evident, nu vei putea să creezi alte aplicații folosind aceste domenii, pentru că ele sunt deja deținute de companiile în cauză.
"api" este doar o convenție și este total opțională. Poți pur și simplu să excluzi această parte din structura URL-ului tău, nu va face niciun fel de diferență. Este totuși o bună practică să îl adaugi, mai ales dacă sub același domeniu ai și aplicația client side care consumă acest API.
Adică dacă ai un magazin online la adresa " https://myapp.com", evident nu vei putea avea și API-ul la aceeași adresă, și atunci adaugi acest "/api/" pentru a clarifica mai bine diferențele.
"employees" este resursa pe care vrem să o folosim.
Un API poate pune la dispoziție zeci de astfel de resurse. Fiecare resursă de genul ăsta reprezintă defapt de cele mai multe ori, o tabelă dintr-o bază de date, atunci când aplicația folosește baze de date relaționale.
"1" reprezintă ID-ul resursei asupra căreia vrem să acționăm. Fie că vrem să citim date despre resursa respectivă, fie că vrem să o actualizăm sau să o ștergem, acesta este un URL universal valabil.
Nu putem, evident, să creăm o resursă folosind acest URL, pentru că ID-ul trebuie să aibă o valoare unicată.

Cu "?category=food" este o situație mai specială pentru că se folosește ceea ce se numește "Query String", adică o modalitate de a filtra printr-o listă de elemente, folosind acest format de URL.
Structura lui zic eu că ne spune destul de multe, vrem să extragem din lista doar acele produse care sunt în categoria "food". Acest "Query String" ne permite de cele mai multe ori să filtrăm folosind mai multe câmpuri sau proprietăți ale resursei respective.

Concluzie
REST sau RESTful (REST e conceptul arhitectural, iar RESTful e un API care se supune reguilor REST, le vei vedea folosite interschimbabil) e un stil arhitectural folosit pe scară largă în aplicațiile sau sistemele mari și foarte mari, enterprise, dar nu întotdeauna regulile definite sunt respectate cu strictețe.
E posibil să vezi destul de des reinterpretări ale acestei arhitecturi, dar e bine să știi ce presupune exact. Dacă toate sistemele care pretind că aderă la paradigma REST ar respecta mai bine regulile, programatorii s-ar putea adapta unui proiect nou mult mai rapid. Dar din păcate, chestia asta nu se întâmplă întotdeauna.
Cam atât pentru azi, ne auzim data viitoare.