Nije REST svaki API
Napravio si HTTP API intefejs (endpoints) i nazivaš ga “REST API”. Najverovatnije je da nisi u pravu. No ne brini, svima nam se to događa. REST je nešto više.
Najkraća definicija REST-a je sadržana u sledećoj formuli:
WWW := URI + HTTP + MIME + Hypermedia.
REST je način da se ostvari inter-operabilinost između kompjuterskih sistema na Internetu. Korišćenjem protokola, tipova sadržaja i URI-ja se definišu resursi i način kako se njima manipuliše. No bez hypermedia
nema potpunog REST APIja.
REST nije specifikacija, već preporuka. To čini stvari podložnim različitim tumačenjima i implementacijama. Kako bilo, neka pravila se mogu izvući. Ipak, to su i dalje samo predlozi (ovde i subjektivni), a ne definicije koje treba slepo slediti.
I još nešto: napravi REST API nije nimalo jednostavno.
Odlike REST APIja
Koristi množinu za listu resursa, a jedninu za konkretan resurs
GET /users
GET /user/123
Međutim, češći je slučaj da se koristi množina u oba slučaja:
GET /users/173
ID resursa je deo URI; atributi se navode u parametrima
Kada se resurs dobavlja svojim ID, on se navodi u URI. Primer:
GET /users/173
Resurs koji se dobavlja pretragom po nekom od atributa:
GET /users?email=joe@oblac.com
Svaki resurs ima link
na sebe
GET /user/173
{
"id" : 173,
"name" : "Joe",
"_links": {
"self":{"href": "http://oblac.com/user/173"},
"html":{"href": "http://oblac.com/user.html?id=173"}
}
}
Lista resursa sadrži navigacione linkove
GET /users?start=15
{
"result": [
{"id": 1},
{"id": 2},
...
],
"_links": {
"prev" : {"href" : "http://oblac.com/users?start=10"},
"next" : {"href" : "http://oblac.com/users?start=20"},
"first": ...
"last" : ...
}
}
Vrati kompozitni resurs kada to ima smisla
Kada resurs ima smisla jedino u kontekstu roditelja, vrati ga ugnježdenog:
GET /persons/1
{
"name" : "Freedy",
"address" : {
"type" : "home",
"street" : "Elm street"
}
}
Ali isto tako:
GET /persons/1/address
{
"type" : "home",
"street" : "Elm street"
}
Zavisno od načina korišćenja treba identifikovati nove resurese koji su agregacija postojećih da bi smanjili učestanost komunikacije sa serverom.
Tretiraj atribute resursa kao posebne resurse
Ako je element resursa dovoljno važan i često se koristi, može da predstavlja resurs za sebe. Primer:
GET /users/173/name
GET /users/ids
POST vs PUT
PUT
je idempotentna operacija: ako se ponovi više puta, rezultat je uvek isti. PUT
služi da napravi resurs ako ne postoji ili da izmeni postojeći resurs.
POST
uvek pravi novi resurs.
Dakle:
POST /report
PUT /report/1029
Parcijalne izmene
Često treba izmeniti nekoliko atributa resursa. Obično se to postiže slanjem PUT
requesta sa delimično definisanim resursom:
PUT /users/123
{"status":false}
Alternativno se može koristi PATCH
metod, noviji, pa stoga i manje podržan.
HATEOAS
Princip hipermedije je da svaki HTTP response sadrži linkove koji korespondiraju na sve akcije koje klijent može da izvrši. Dakle, zavisno od trenutnog stanja aplikacije, svaki response opisuje sve akcije koje su dostupne. Server dinamički menja koje su akcije dostupne, a klijent bi trebalo da se sam adaptira na izmene.
Trenutno stanje resursa je kombinacija:
- vrednosti atributa koji pripadaju resursu,
- linkova na resurse koji su po prirodi stvari povezani sa trenutnim resursom,
- linkova koji predstavljaju tranziciju na buduće stanje trenutnog resursa,
- biznis operacija koje se mogu izvršiti na resursu.
HATEOAS (Hypermedia as the Engine of Application State) je krajnji nivo u poznatoj lestvici zrelosti REST APIja koju je sastavio Martin Fowler. Ova osobenost REST APIja pruža informacije kako navigirati i koristiti REST API dinamički, uključujući hipermedia linkove u response.
Jednostavan test za vaš API može biti sledeće: dovuci resurs i probaj da navigiraš kroz sve ponuđene linkove. Na sličan način kako prolaziš Web sajtom prateći linkove, tako i ovde, u domenu REST APIja, bi trebalo da možeš da dođeš do svih drugih resursa i akcija koje se mogu izvesti nad njima. Simple as that.