Tanácsok REST API tervezéshez

2018. december 16.

Ha az alkalmazásunkhoz egy REST API-t szeretnénk készíteni, akkor sok mindenre kell ügyelnünk, hogy az megfeleljen az üzleti igényeknek, legyen könnyen felhasználható, illetve hogy a későbbiek során a karbantartása is egyszerű maradjon. 

Olyan dolgokra kell figyelni, mint a hívások felépítése, a hívásokra adott válasz egységessége vagy éppen a verziókezelés. 

Hivatalos szabvány nem létezik, de Roy Fielding 2000-ben publikált disszertációjából ki lehet indulni. Ebben definiálja, hogy mikor is nevezhető valami RESTfulnak. Hat ilyen fő kritérium létezik, de most nem ezekre helyezném a hangsúlyt, hanem inkább arra, hogy a kérések struktúráját hogyan alakítsuk ki úgy, hogy az hierarchikus legyen, és mindent arra használjunk, amire való.

HTTP metódusok

Itt főként a leggyakoribb metódusokat (verbs) szeretném kiemelni, melyek főként CRUD műveletekhez kapcsolhatók, de persze vannak még egyéb metódusok is, amelyeket a HTTP protokoll definiál.

Azt kell szem előtt tartanunk, hogy ezek a metódusok lesznek az igéink, amik megmondják, hogy mit csinálunk azokkal az erőforrásokkal, amelyeket majd főnevek segítségével azonosítunk.

GET

A GET kéréseket arra használjuk, hogy adatokat kérjünk le, és jobb esetben 200-as (OK) kóddal, rosszabb esetben 404-es (NOT FOUND), vagy 400-as (BAD REQUEST) kóddal tér vissza. Minden esetben csak az adat olvasására használható, semmilyen változást, mellékhatást nem szabad kiváltania. Pont ettől lesz ez az egyik biztonságos művelet, illetve idempotens is, azaz akárhányszor lekérve ugynaazt az adatot, ugyanazt a választ fogjuk kapni.

POST

POST kérésekkel mindig létrehozunk valamit és ha ez sikeres volt, akkor 201-es (CREATED) kódot kapunk vissza.  Ezek a kérések se nem biztonságosak, se nem idempotensek.

PUT

PUT kéréseket módosításra használjuk. Ilyenkor az erőforrás új állapotát küldjük fel a szervernek a kérés törzsében. Sikeres módosítás esetén 200-as, esetleg 204-es (NO CONTENT) kódot kapunk vissza. Nem biztonságos, mert módosítja a szerver állapotát, de idempotens, mert akárhányszor küldjük ugyanazt a kérést, nem módosul az állapot.

DELETE

Talán a legkevésbé problémás kérés, a DELETE segítségével törölhetünk már létező adatokat. Sikeres törlés esetén 200-as kóddal tér vissza. Természetesen nem biztonságos, de elméletben idempotens, hisz többször meghívva ugyanarra, az eredmény ugyanaz lesz, azaz nem fog létezni. 

Útvonalak elnevezése

Ez talán a legtöbbet vitatott, mégis a legfontosabb része az API tervezésének. Ha jól vannak elnevezve az erőforrásokhoz vezető utak, akkor az API intuitív és könnyen használható lesz.

Alapvetően minden erőforrásnak saját, egyedi neve van, melyet akár több útvonalon keresztül is elérhetünk. Ez az egyedi cím (URI) segít abban, hogy a kérésünkben megnevezzük, hogy mivel szeretnék csinálni valamit, és hogy mit, azt a fent említett metódusok szabják meg.

Egy jól megtevezett REST API esetén ezek az URI-k kiszámíthatóak, és hierarchikusan felépítettek, amelyben az alá- vagy fölérendeltségi viszony mutatja meg, hogy a különböző erőforrások milyen kapcsolatban állnak egymással. 

A könnyebbség kedvéért egy példán keresztül mutatnám be, hogy hogyan is lehet ezt jól megvalósítani. A példában tegyük fel, hogy egy webáruház API-ját tervezzük és az adatbázisunkban vannak vásárlók (customer), termékek (product) és rendelések (order).

Új vásárló beszúrásához:
POST /api/customers

A 123-as azonosítójú vásárló lekérdezéséhez:
GET /api/customers/123
(ugyanezt az útvonalat használhatnánk ennek a vásárló adatainak módosítására, illetve törlésére is)

A kiválasztott vásárlónak egy új rendelésének elmentésére:
POST /api/customers/123/orders

Ha ezt elmentette mondjuk a 456-os azonosítóval, akkor elérhetjük:
GET /api/customers/123/orders/456

Vegyük észre, hogy ezt akár így is elérhetjük (a vásárló ismerete nélkül):
GET /api/orders/456

Ha pedig szeretnénk egy listát az adott rendelésben szereplő termékekről:
GET /api/customers/123/orders/456/products
(itt már 3 szint mélyen vagyunk a hierarchiában, így helyette használhajuk a rövidebb útvonalat is)

Remélem, hogy ezekből összeállt a hierarchia koncepciója. 

Abból is nagy viták szoktak lenni, hogy a használt főnevek egyes vagy többes számban szerepeljenek az útvonalakban, de inkább a többes szám használata a gyakoribb, és szerintem is így logikusabban is olvasható, például: “a vásárlók közül a 123-as azonosítójút kiválasztva, neki a rendelései közül a 456-os azonosítójúhoz tartozó termékek”. Persze vannak olyan esetek is, amikor a többes számnak nincs sok értelme, például ha valamiből ténylegesen egy van. Ha például egy adott vásárló címét szeretném megtudni, akkor a következő kérést küldhetem:
GET /api/customers/123/address

Összefoglalás

Mint a szoftveres világban mindenhol, egy REST APi tervezésekor is nagyon fontos a következetes nevezéktan. Ha néhány egyszerű szabály követünk, akkor ezt könnyedén elérhetjük.

1 hozzászólás

  • Szia!
    Jó cikk! Érdemes lehet még esetleg megemlíteni a PATCH “metódust” is. 😉

Vélemény, hozzászólás?

Az email címet nem tesszük közzé. A kötelező mezőket * karakterrel jelöltük