Ebben a bemutatóban megismerkedünk a különböző REST specifikus státusz kódokkal és rövid betekintést teszünk a REST-kérések típusaira is.
Státus kód: 200 (OK)
Ez azt jelzi, hogy a REST API sikeresen végrehajtotta az ügyfél által kért műveletet, és hogy a 2xx sorozatban nincs szükség különlegesebb kódra.
A 204-es állapotkóddal ellentétben a 200-as válasznak tartalmaznia kell egy választestet. A válasszal együtt visszaküldött információ a kérelemben használt módszertől függ, például:
- GET a válaszban a kért erőforrásnak megfelelő entitás kerül elküldésre;
- HEAD a kért erőforrásnak megfelelő entitásfejléc-mezők kerülnek elküldésre a válaszban üzenettest nélkül;
- POST a művelet eredményét leíró vagy azt tartalmazó entitás;
- TRACE egy olyan entitás, amely a kérési üzenetet tartalmazza, ahogyan azt a végkiszolgáló fogadta.
Státus kód: 201 (Létrehozva)
A REST API a 201-es állapotkóddal válaszol, amikor egy erőforrás jön létre egy gyűjteményen belül. Előfordulhat olyan eset is, amikor egy új erőforrás valamilyen vezérlői művelet eredményeként jön létre, ebben az esetben a 201 szintén megfelelő válasz.
Az újonnan létrehozott erőforrásra a válasz entitásában visszaküldött URI(k) segítségével lehet hivatkozni, az erőforrás legkonkrétabb URI-ját a Location fejlécmező adja meg.
A 201-es állapotkód visszaküldése előtt az eredetkiszolgálónak létre KELL hoznia az erőforrást. Ha a művelet nem hajtható végre azonnal, a kiszolgálónak 202 (Elfogadva) válaszjelet KELL adnia.
Státus kód: 202 (Elfogadva)
A 202-es választ általában olyan műveleteknél használják, amelyek feldolgozása hosszú időt vesz igénybe. Azt jelzi, hogy a kérelmet feldolgozásra elfogadták, de a feldolgozás még nem fejeződött be. A kérést végül lehet, hogy feldolgozzák, de az is lehet, hogy nem, sőt, hogy a feldolgozás során a kérést elutasítják.
Célja, hogy lehetővé tegye a kiszolgáló számára, hogy elfogadjon egy kérést valamilyen más folyamathoz (esetleg egy kötegelt folyamathoz, amely naponta csak egyszer fut le) anélkül, hogy a felhasználói ügynöknek a kiszolgálóval való kapcsolata a folyamat befejezéséig fennmaradna.
Az ezzel a válasszal visszaküldött entitásnak tartalmaznia KELL a kérés aktuális állapotának jelzését és vagy egy állapotfigyelőre mutató mutatót (a munkasorok helyét), vagy valamilyen becslést arra vonatkozóan, hogy a felhasználó mikorra számíthat a kérés teljesítésére.
Státus kód: 204 (Nincs tartalom)
A 204-es állapotkódot általában PUT, POST vagy DELETE kérésre válaszul küldik, amikor a REST API nem küld vissza semmilyen állapotüzenetet vagy reprezentációt a válaszüzenet testében.
Az API a 204-es kódot egy GET-kérelemmel együtt is küldheti, hogy jelezze, hogy a kért erőforrás létezik, de nincs olyan állapotreprezentáció, amelyet a válasz törzsébe (response body) lehetne foglalni.
Ez a válasz elsősorban arra szolgál, hogy lehetővé tegye a műveletek bevitelét anélkül, hogy a felhasználói ügynök aktív dokumentumnézetének megváltoztatását okozná. Azonban minden új vagy frissített metainformációt KELL alkalmazni a felhasználói ügynök dinamikus nézetében lévő dokumentumra.
A 204-es válasz NEM tartalmazhat message-body-t, ezért mindig a fejlécmezők utáni első üres sor zárja le.
Státus kód: 301 (Álandó áthelyezés)
A 301-es állapotkód azt jelzi, hogy a REST API erőforrásmodellje jelentősen átalakult, és az ügyfél által kért erőforráshoz új állandó URI-t rendeltek. A REST API-nak meg kell adnia az új URI-t a válasz Location fejlécében, és minden jövőbeli kérést a megadott URI-hoz kell irányítani.
Ezt a válaszkódot aligha fogja használni az API-ban, mivel az API verziószámát mindig használhatja az új API-hoz, miközben megtartja a régit.
Státus kód: 302 (megtalálható)
A 302 Found HTTP-válaszállapotkód az URL átirányításának gyakori módja. Az ezzel az állapotkóddal adott HTTP-válasz a Location fejléc mezőben egy URL-címet is megad. A felhasználói ügynököt (pl. a webböngészőt) az ezzel a kóddal adott válasz arra kéri, hogy tegyen egy másodikat. Egyébként azonos, a Location mezőben megadott új URL címre irányuló kérést.
Sok webböngésző ezt a kódot a szabványt sértő módon valósította meg, az új kérés kéréstípusát GET-re változtatva, függetlenül az eredeti kérésben használt típustól (pl. POST). Az RFC 1945 és az RFC 2068 előírja, hogy az ügyfél nem változtathatja meg az átirányított kérés módszerét. A 303-as és 307-es állapotkódok olyan kiszolgálók számára kerültek be, amelyek egyértelműen egyértelművé kívánják tenni, hogy milyen reakciót várnak el az ügyféltől.
Státus kód: 303 (Lásd: Egyéb)
A 303-as válasz azt jelzi, hogy a vezérlő erőforrás befejezte a munkáját, de a potenciálisan nem kívánt választest küldése helyett az ügyfélnek egy válasz erőforrás URI-jét küldi. A válasz lehet az ideiglenes állapotüzenet URI-je, vagy valamilyen már létező, állandóbb erőforrás URI-je.
Általánosságban elmondható, hogy a 303 állapotkód lehetővé teszi a REST API számára, hogy egy erőforrásra való hivatkozást küldjön anélkül, hogy az ügyfelet az erőforrás állapotának letöltésére kényszerítené. Ehelyett az ügyfél GET-kérést küldhet a Location fejléc értékére.
A 303-as választ NEM szabad gyorsítótárba helyezni, de a második (átirányított) kérésre adott válasz lehet, hogy gyorsítótárba helyezhető.
Státus kód: 304 (Nincs módosítás)
Ez az állapotkód hasonló a 204-eshez (“Nincs tartalom”), mivel a választestnek üresnek kell lennie. A lényeges különbség az, hogy a 204-es kódot akkor kell használni, ha nincs mit elküldeni a testben, míg a 304-es kódot akkor kell használni, ha az erőforrás nem módosult a kérés If-Modified-Since vagy If-None-Match fejlécében megadott verzió óta.
Ilyen esetben nincs szükség az erőforrás újbóli elküldésére, mivel az ügyfélnek még mindig van egy korábban letöltött példánya.
Ennek használata sávszélességet és újrafeldolgozást takarít meg mind a kiszolgáló, mind az ügyfél számára, mivel csak a fejlécadatokat kell elküldeni és fogadni, szemben azzal, hogy a teljes oldalt a kiszolgáló újra feldolgozza, majd újra elküldi, ami több sávszélességet igényel a kiszolgáló és az ügyfél számára.
Státus kód: 307 (ideiglenes átirányítás)
A 307-es válasz azt jelzi, hogy a REST API nem fogja feldolgozni az ügyfél kérését. Ehelyett az ügyfélnek újra el kell küldenie a kérést a válaszüzenet Location fejlécében megadott URI-hoz. A jövőbeli kéréseknek azonban továbbra is az eredeti URI-t kell használniuk.
A REST API ezt az állapotkódot arra használhatja, hogy az ügyfél által kért erőforráshoz ideiglenes URI-t rendeljen. A 307-es válasz például arra használható, hogy az ügyfél kérését egy másik állomáshoz helyezze át.
Az ideiglenes URI-t a válasz Location mezőjében KELL megadni. Hacsak a kérés módszere nem HEAD volt, a válasz egységének tartalmaznia szükséges egy rövid hipertext megjegyzést az új URI(k)-ra mutató hiperhivatkozással.
Ha a 307-es státuszkódot nem GET vagy HEAD kérésre kapjuk válaszul, a felhasználói ügynök NEM irányíthatja át automatikusan a kérést, kivéve, ha a felhasználó ezt meg tudja erősíteni, mivel ez megváltoztathatja a kérés kibocsátásának feltételeit.
Státus kód: 400 (Rossz kérés)
A 400 az általános ügyféloldali hibaállapot, amelyet akkor használnak, ha más 4xx hibakód nem megfelelő. A hibák lehetnek például hibás kérés szintaxis, érvénytelen kérési üzenet paraméterek, vagy megtévesztő kérés útvonalvezetés stb.
Az ügyfélnek NEM KELL megismételnie a kérést módosítások nélkül.
Státus kód: 401 (Nem engedélyezett)
A 401-es hibaválasz azt jelzi, hogy az ügyfél a megfelelő jogosultság megadása nélkül próbált meg egy védett erőforrással operálni. Előfordulhat, hogy rossz hitelesítő adatokat adott meg, vagy egyáltalán nem adott meg ilyeneket. A válasznak tartalmaznia kell egy WWW-Authenticate fejlécmezőt, amely a kért erőforrásra vonatkozó kihívást tartalmazza.
Az ügyfél megismételheti a kérést egy megfelelő Authorization fejlécmezővel. Ha a kérés már tartalmazta az Authorization hitelesítő adatokat, akkor a 401-es válasz azt jelzi, hogy az engedélyezést elutasították az adott hitelesítő adatokra vonatkozóan. Ha a 401-es válasz ugyanazt a kihívást tartalmazza, mint az előző válasz, és a felhasználói ügynök már legalább egyszer megkísérelte a hitelesítést, akkor a felhasználónak a válaszban megadott entitást KELL bemutatni, mivel ez az entitás releváns diagnosztikai információkat tartalmazhat.
Státus kód: 403 (Hozzáférés megtagadva)
A 403-as hibaválasz azt jelzi, hogy az ügyfél kérelme helyesen van kialakítva, de a REST API nem hajlandó teljesíteni azt, azaz a felhasználó nem rendelkezik az erőforráshoz szükséges jogosultságokkal. A 403-as válasz nem az ügyfél elégtelen hitelesítő adatainak esete; ez a 401-es (“Unauthorized”) válasz lenne.
A hitelesítés nem segít, és a kérést NEM KELL megismételni. A 401 Nem engedélyezett válasszal ellentétben a hitelesítés nem változtat semmin.
Státus kód: 404 (Nem található)
A 404-es hibaállapotkód azt jelzi, hogy a REST API nem tudja az ügyfél URI-ját egy erőforráshoz rendelni, de a jövőben talán elérhető lesz. Az ügyfél későbbi kérései megengedettek.
Nem jelzi, hogy az állapot ideiglenes vagy állandó. A 410 (Gone) állapotkódot akkor KELL használni, ha a kiszolgáló valamilyen belsőleg konfigurálható mechanizmuson keresztül tudja, hogy egy régi erőforrás tartósan nem elérhető, és nincs továbbítási címe. Ezt az állapotkódot általában akkor használják, ha a kiszolgáló nem kívánja felfedni, hogy pontosan miért utasították el a kérést, vagy ha más válasz nem alkalmazható.
Státus kód: 405 (A módszer nem engedélyezett)
Az API 405-ös hibaüzenettel válaszol, jelezve, hogy az ügyfél olyan HTTP-módszert próbált használni, amelyet az erőforrás nem engedélyez. Például egy csak olvasható erőforrás csak a GET és a HEAD módszert támogatja, míg egy vezérlő erőforrás a GET és a POST módszert engedélyezheti, de a PUT vagy DELETE módszert nem.
A 405-ös válasznak tartalmaznia kell az Allow fejlécet, amely felsorolja az erőforrás által támogatott HTTP-módszereket. Például:
Allow: GET, POST
Státus kód: 406 (Nem elfogadható)
A 406-os hibaválasz azt jelzi, hogy az API nem képes létrehozni az ügyfél által preferált médiatípusok egyikét sem, ahogyan azt az Accept kérésfejléc is jelzi. Például az application/xml formátumú adatokra vonatkozó ügyfélkérés 406-os választ kap, ha az API csak application/json formátumú adatokat hajlandó formázni.
Ha a válasz elfogadhatatlan, a felhasználói ügynöknek ideiglenesen le kell állítania a további adatok fogadását, és le kell kérdeznie a felhasználót, hogy döntsön a további lépésekről.
Státus kód: 412 (Előfeltétel nem teljesült)
A 412-es hibaválasz azt jelzi, hogy az ügyfél egy vagy több előfeltételt adott meg a kérés fejlécében, gyakorlatilag azt üzenve a REST API-nak, hogy csak akkor hajtsa végre a kérést, ha bizonyos feltételek teljesülnek. A 412-es válasz azt jelzi, hogy ezek a feltételek nem teljesültek, ezért az API a kérés végrehajtása helyett ezt az állapotkódot küldi.
Státus kód: 415 (Nem támogatott médiatípus)
A 415-ös hibaválasz azt jelzi, hogy az API nem tudja feldolgozni az ügyfél által megadott médiatípust, ahogyan azt a Content-Type kérési fejléc is jelzi. Például az application/xml formátumú adatokat tartalmazó ügyfélkérés 415-ös választ kap, ha az API csak az application/json formátumú adatokat hajlandó feldolgozni.
Például az ügyfél image/svg+xml formátumban tölt fel egy képet, de a kiszolgáló más formátumú képeket kér.
Státus kód: 500 (belső szerverhiba)
Az 500 az általános REST API hibaválasz. A legtöbb webes keretrendszer automatikusan ezzel a válaszállapotkóddal válaszol, amikor valamilyen kivételeket előidéző kéréskezelő kódot hajt végre.
Az 500-as hiba soha nem az ügyfél hibája, ezért ésszerű, hogy az ügyfél megismétli ugyanazt a kérést, amely ezt a választ kiváltotta, és reméli, hogy más választ kap.
Az API-válasz az általános hibaüzenet, amelyet akkor adnak meg, ha váratlan körülmény lépett fel, és ennél specifikusabb üzenet nem alkalmas.
Státus kód: 501 (Nem megvalósított, nincs még implementálva)
A kiszolgáló vagy nem ismeri fel a kérési módszert, vagy nem tudja teljesíteni a kérést. Általában ez jövőbeli elérhetőséget jelent (pl. egy webszolgáltatás API új funkciója).
