Free Press

A REST API-k lehetővé teszik, hogy bármilyen webes alkalmazást fejlesszünk, amely minden lehetséges CRUD (create, retrieve, update, delete) művelettel rendelkezik. A REST-irányelvek azt javasolják, hogy egy adott HTTP-módszert használjunk egy adott típusú, a kiszolgálóhoz intézett híváshoz (bár technikailag lehetséges ezt az irányelvet megszegni, de ez erősen nem javasolt).

Az alábbiakban megadott információk segítségével keresse meg az API által végzett művelethez megfelelő HTTP-módszert.

Table of ContentsHTTP GETHTTP POSTHTTP PUTHTTP DELETEHTTP PATCHSummaryGlossary

HTTP GET

A GET-kéréseket csak az erőforrások reprezentációjának/információjának lekérdezésére használja – és semmilyen módon nem módosíthatja azokat. Mivel a GET-kérések nem változtatják meg az erőforrás állapotát, ezeket biztonságos módszereknek mondjuk. Ezenkívül a GET API-knak idempotensnek kell lenniük, ami azt jelenti, hogy több azonos kérésnek minden alkalommal ugyanazt az eredményt kell produkálnia, amíg egy másik API (POST vagy PUT) meg nem változtatja az erőforrás állapotát a szerveren.

Ha a Request-URI egy adattermelő folyamatra utal, akkor az előállított adatokat kell visszaadni a válaszban entitásként, és nem a folyamat forrásszövegét, kivéve, ha ez a szöveg történetesen a folyamat kimenete.

Minden adott HTTP GET API esetében, ha az erőforrás megtalálható a kiszolgálón, akkor 200 (OK) HTTP válaszkódot kell visszaküldenie – a választesttel együtt, amely általában vagy XML vagy JSON tartalom (platformfüggetlen jellegük miatt).

Ha az erőforrás NEM található a kiszolgálón, akkor 404 (NOT FOUND) HTTP válaszkódot kell visszaküldenie. Hasonlóképpen, ha megállapítást nyer, hogy maga a GET kérés nem megfelelően van kialakítva, akkor a kiszolgáló 400 (BAD REQUEST) HTTP válaszkódot fog visszaküldeni.

Példa kérés URI-k

• HTTP GET http://www.appdomain.com/users
• HTTP GET http://www.appdomain.com/users?size=20&page=5
• HTTP GET http://www.appdomain.com/users/123
• HTTP GET http://www.appdomain.com/users/123/address

HTTP POST

A POST API-k használata új alárendelt erőforrások létrehozására, pl.:, egy fájl az azt tartalmazó könyvtárnak van alárendelve, vagy egy sor egy adatbázis táblának van alárendelve. Ha szigorúan a REST szempontjából beszélünk, a POST módszereket arra használjuk, hogy új erőforrást hozzunk létre az erőforrások gyűjteményében.

Egy erőforrás létrehozása esetén a válasznak HTTP válaszkóddal 201 (Created) KELL lennie, és tartalmaznia KELL egy entitást, amely leírja a kérés állapotát és utal az új erőforrásra, valamint egy Location fejlécet.

Néhányszor előfordulhat, hogy a POST módszer által végrehajtott művelet nem eredményez URI-vel azonosítható erőforrást. Ebben az esetben vagy a 200 (OK) vagy a 204 (No Content) HTTP válaszkód a megfelelő válaszállapot.

Az erre a módszerre adott válaszok nem gyorsítótárba helyezhetők, kivéve, ha a válasz megfelelő Cache-Control vagy Expires fejlécmezőt tartalmaz.

Figyeljen arra, hogy a POST nem biztonságos és nem idempotens, és két azonos POST kérés meghívása két különböző, azonos információt tartalmazó erőforrást fog eredményezni (kivéve az erőforrás azonosítókat).

Példa kérés URI-k

• HTTP POST http://www.appdomain.com/users
• HTTP POST http://www.appdomain.com/users/123/accounts

HTTP PUT

A PUT API-kat elsősorban meglévő erőforrás frissítésére használja (ha az erőforrás nem létezik, akkor az API dönthet úgy, hogy létrehoz egy új erőforrást vagy nem). Ha a PUT API új erőforrást hozott létre, az eredeti kiszolgálónak tájékoztatnia KELL a felhasználói ügynököt a 201 (Created) HTTP válaszkódú válaszon keresztül, ha pedig egy meglévő erőforrás módosul, akkor a 200 (OK) vagy 204 (No Content) válaszkódokat KELL küldeni a kérés sikeres befejezésének jelzésére.

Ha a kérés egy gyorsítótáron halad át, és a Request-URI egy vagy több jelenleg gyorsítótárban tárolt entitást azonosít, ezeket a bejegyzéseket elavultként KELL kezelni. Az erre a módszerre adott válaszok nem tárolhatók a gyorsítótárban.

Példa kérési URI-k

• HTTP PUT http://www.appdomain.com/users/123
• HTTP PUT http://www.appdomain.com/users/123/accounts/456

HTTP DELETE

Amint a neve is mutatja, a DELETE API-kat erőforrások (a kérés-URI által azonosított) törlésére használják.

A DELETE-kérelmek sikeres válaszának a code 200 (OK) HTTP-válasznak KELL lennie, ha a válasz tartalmaz egy állapotot leíró entitást, 202 (Accepted) ha a művelet sorba került, vagy 204 (No Content) ha a művelet végrehajtásra került, de a válasz nem tartalmaz entitást.

A DELETE műveletek idempotensek. Ha egy erőforrást DELETE-olunk, akkor az eltávolításra kerül az erőforrások gyűjteményéből. A DELETE API ismételt meghívása az adott erőforráson nem változtatja meg az eredményt – azonban a DELETE másodszori meghívása egy erőforráson 404-es (NOT FOUND) választ ad vissza, mivel az erőforrás már eltávolításra került. Egyesek azzal érvelhetnek, hogy ez nem teszi a DELETE metódust nem-idempotenssé. Ez vita és személyes vélemény kérdése.

Ha a kérés áthalad egy gyorsítótáron, és a Request-URI azonosít egy vagy több jelenleg gyorsítótárban lévő entitást, akkor ezeket a bejegyzéseket elavultként KELL kezelni. Az erre a módszerre adott válaszok nem tárolhatók a gyorsítótárban.

Példa kérés URI-k

• HTTP DELETE http://www.appdomain.com/users/123
• HTTP DELETE http://www.appdomain.com/users/123/accounts/456

HTTP PATCH

HTTP PATCH kérések egy erőforrás részleges frissítésére szolgálnak. Ha azt látja, hogy a PUT kérések is módosítanak egy erőforrás entitást, így hogy egyértelműbbé tegyük – a PATCH módszer a helyes választás egy meglévő erőforrás részleges frissítésére, és a PUT csak akkor használható, ha egy erőforrást teljes egészében lecserélünk.

Kérjük, vegye figyelembe, hogy van néhány kihívás, ha úgy dönt, hogy a PATCH API-kat használja az alkalmazásában:

• A PATCH támogatása a böngészőkben, szerverekben és webes alkalmazás keretrendszerekben nem általános. Az IE8, a PHP, a Tomcat, a Django és sok más szoftver hiányzik vagy nem támogatja.
• A PATCH-kérés hasznos terhe nem olyan egyszerű, mint a PUT-kérésé. Pl.

  HTTP GET /users/1

  az alábbi választ adja:

  {id: 1, username: 'admin', email: ''}

  Egy minta patch-kérés az e-mail frissítésére a következő lesz:

  HTTP PATCH /users/1

  ” }
  ]

A HTTP specifikáció szerint a következő lehetséges műveletek lehetnek.

},
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy","from": "/a/b/d", "path": "/a/b/e" }
]

A PATCH módszer nem helyettesíti a POST vagy PUT módszereket. A teljes erőforrás cseréje helyett egy deltát (diff) alkalmaz.

A RESTful API-k HTTP-módszereinek összefoglalása

Az alábbi táblázat összefoglalja a fent tárgyalt HTTP-módszerek használatát.

Glosszárium

Biztonságos módszerek

A HTTP specifikáció szerint a GET és HEAD módszereket csak erőforrás-reprezentációk lekérdezésére szabad használni – és nem frissítik/törlik az erőforrást a szerveren. Mindkét módszert “biztonságosnak” mondják.

Ez lehetővé teszi a felhasználói ügynökök számára, hogy más módszereket, például a POST, PUT és DELETE módszereket egyedi módon ábrázoljanak, hogy a felhasználó tudatosítsa, hogy egy esetlegesen nem biztonságos műveletet kérnek – és ezek frissíthetik/törölhetik az erőforrást a szerveren, ezért óvatosan kell használni őket.

Idempotens módszerek

Az idempotens kifejezést átfogóbban olyan művelet leírására használjuk, amely egyszeri vagy többszöri végrehajtás esetén is ugyanazt az eredményt adja. Az idempotencia sok helyzetben praktikus tulajdonság, mivel azt jelenti, hogy egy művelet annyiszor ismételhető vagy próbálható újra, ahányszor csak szükséges, anélkül, hogy nem kívánt hatásokat okozna. A nem idempotens műveletek esetében az algoritmusnak nyomon kell követnie, hogy a műveletet már végrehajtották-e vagy sem.

A HTTP specifikációban a GET, HEAD, PUT és DELETE metódusok idempotensnek vannak deklarálva. A többi metódusnak OPTIONS és TRACE NEM KELL, hogy mellékhatásai legyenek, így mindkettő eredendően idempotens.