A REST API hypertext-driven legyen
Bár erős vitákat tapasztalok a REST körül, valahogy a hypertext-driven API-val ritkán találkozom.
Roy T. Fielding, a REST megálmodója a gyakran idézett REST APIs must be hypertext-driven cikkjében a következőt mondja:
In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period.
Erre erősít rá a Richardson Maturity Model is, mely három lépésben mutatja be a REST alapvető elemeit:
- Level 1 - Resources
- Level 2 - HTTP Verbs
- Level 3 - Hypermedia Controls
És egy API csak akkor nevezhető RESTfulnak, ha az összes szinten leírtakat teljesíti, igen a hypermedia control használatát is.
De mit is jelent ez? Az állítás egyszerű: a kliensnek minden előzetes tudás nélkül igénybe kell tudnia venni a RESTful API mögötti szolgáltatásokat, és ez linkek segítségével valósulhat meg.
Pl. az előző Workflow REST API-n posztomban szereplő Issue Tracker alkalmazás a következőképp adja vissza a hibajegyek listáját:
{
"_embedded": {
"jtl:issueResourceList": [
{
"id": 1,
"title": "Write a post about REST",
"state": "NEW",
"_links": {
"self": {
"href": "http://localhost:8080/api/issues/1"
},
"actions": {
"href": "http://localhost:8080/api/issues/1/actions"
}
}
}
]
},
"_links": {
"self": {
"href": "http://localhost:8080/api/issues"
}
}
}
Látható a hibajegyek listáját reprezentáló URL-jét tartalmazó self link, valamint hibajegyenként
a hibajegyet reprezentáló URL-jének linkje szintén self névvel, valamint a hibajegyhez tartozó
lépéseket reprenzentáló URL actions névvel.
Ez a Hypermedia as the engine of application state (HATEOAS), melyet szintén Roy T. Fielding vezetett be a disszertációjában. A HATEOAS szerint a szerver a kliens számára linkekkel jelzi, hogy mit tehet.
Az elv mögötte az, hogy a REST API-t is úgy lehessen használni, mint a webet. Ahol vannak oldalak és linkek és semmilyen előzetes információra nincs szükségem a használatához.
Hogy hogyan viszonyul ez az OpenAPI-hoz (Swaggerhez)? Elvileg a cél ugyanaz, és míg a HATEOAS a REST gonolatiságához illeszkedik, az OpenAPI inkább az RPC-hez.
