Free Press

REST API umožňují vyvíjet libovolné webové aplikace se všemi možnými operacemi CRUD (create, retrieve, update, delete). Směrnice REST doporučují používat konkrétní metodu HTTP na určitý typ volání na server (ačkoli technicky je možné tuto směrnici porušit, přesto se to velmi nedoporučuje).

Pomocí níže uvedených informací najděte vhodnou metodu HTTP pro akci prováděnou rozhraním API.

Table of ContentsHTTP GETHTTP POSTHTTP PUTHTTP DELETEHTTP PATCHSummaryGlossary

HTTP GET

Požadavky GET používejte pouze k získání reprezentace/informací o prostředku – a ne k jeho jakýmkoli úpravám. Protože požadavky GET nemění stav prostředku, říká se, že jde o bezpečné metody. Kromě toho by rozhraní API GET měla být idempotentní, což znamená, že provedení několika stejných požadavků musí pokaždé přinést stejný výsledek, dokud jiné rozhraní API (POST nebo PUT) nezmění stav prostředku na serveru.

Pokud se Request-URI vztahuje k procesu produkujícímu data, musí být jako entita v odpovědi vrácena právě produkovaná data, a nikoli zdrojový text procesu, pokud tento text není náhodou výstupem procesu.

Pokud je daný zdroj na serveru nalezen, musí API HTTP GET vrátit kód odpovědi HTTP 200 (OK) – spolu s tělem odpovědi, což je obvykle obsah XML nebo JSON (vzhledem k jejich platformově nezávislé povaze).

V případě, že zdroj na serveru nalezen NENÍ, musí vrátit kód odpovědi HTTP 404 (NOT FOUND). Podobně pokud se zjistí, že samotný požadavek GET není správně vytvořen, pak server vrátí kód odpovědi HTTP 400 (BAD REQUEST).

Příkladové požadavky URI

• 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/adresa

HTTP POST

Pomocí POST API vytvoříte nové podřízené zdroje, např, soubor je podřízený adresáři, který ho obsahuje, nebo řádek je podřízený databázové tabulce. Pokud mluvíme striktně v termínech REST, metody POST se používají k vytvoření nového prostředku do kolekce prostředků.

Pokud byl prostředek vytvořen na původním serveru, odpověď MUSÍ mít kód odpovědi HTTP 201 (Created) a obsahovat entitu, která popisuje stav požadavku a odkazuje na nový prostředek, a hlavičku Location.

Mnohdy nemusí být výsledkem akce provedené metodou POST prostředek, který lze identifikovat pomocí URI. V takovém případě je vhodným stavem odpovědi buď kód odpovědi HTTP 200 (OK), nebo 204 (No Content).

Odpovědi této metody nelze ukládat do mezipaměti, pokud odpověď neobsahuje příslušná pole hlavičky Cache-Control nebo Expires.

Upozorňujeme, že metoda POST není bezpečná ani idempotentní a vyvolání dvou stejných požadavků POST bude mít za následek dva různé prostředky obsahující stejné informace (kromě identifikátorů prostředků).

Příkladové požadavky URI

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

HTTP PUT

Příkazy PUT API používejte především k aktualizaci existujícího prostředku (pokud prostředek neexistuje, pak se API může rozhodnout, zda nový prostředek vytvoří, nebo ne). Pokud byl pomocí rozhraní API PUT vytvořen nový prostředek, MUSÍ o tom původní server informovat agenta uživatele prostřednictvím kódu odpovědi HTTP 201 (Created) a pokud je upraven existující prostředek, MUSÍ být zaslán kód odpovědi 200 (OK) nebo 204 (No Content), který indikuje úspěšné dokončení požadavku.

Prochází-li požadavek mezipamětí a identifikuje-li Request-URI jednu nebo více aktuálně uložených entit, MUSÍ být tyto záznamy považovány za zastaralé. Odpovědi na tuto metodu nelze ukládat do mezipaměti.

Příklad URI požadavků

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

HTTP DELETE

Podle názvu se rozhraní API DELETE používá k odstranění zdrojů (identifikovaných pomocí Request-URI).

Úspěšnou odpovědí požadavků DELETE MUSÍ být odpověď HTTP code 200 (OK), pokud odpověď obsahuje entitu popisující stav, 202 (Accepted), pokud byla akce zařazena do fronty, nebo 204 (No Content), pokud byla akce provedena, ale odpověď neobsahuje entitu.

Operace DELETE jsou idempotentní. Pokud prostředek DELETE, je odstraněn z kolekce prostředků. Opakované volání rozhraní API DELETE na tomto prostředku nezmění výsledek – pokud však zavoláte DELETE na prostředku podruhé, vrátí se zpráva 404 (NOT FOUND), protože již byl odstraněn. Někdo může namítnout, že tím se metoda DELETE stává neidempotentní. Je to věc diskuse a osobního názoru.

Projde-li požadavek mezipamětí a identifikuje-li Request-URI jednu nebo více aktuálně uložených entit v mezipaměti, měly by být tyto záznamy považovány za zastaralé. Odpovědi na tuto metodu nelze ukládat do mezipaměti.

URI příkladů požadavků

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

HTTP PATCH

HTTP PATCH požadavky slouží k částečné aktualizaci prostředku. Pokud vidíte, že požadavky PUT také mění entitu prostředku, tak pro upřesnění – metoda PATCH je správnou volbou pro částečnou aktualizaci existujícího prostředku a PUT by měla být použita pouze v případě, že nahrazujete prostředek celý.

Upozorňujeme, že pokud se rozhodnete použít rozhraní API PATCH ve své aplikaci, existují určité problémy:

• Podpora PATCH v prohlížečích, serverech a frameworcích webových aplikací není univerzální. IE8, PHP, Tomcat, Django a spousta dalšího softwaru má chybějící nebo nefunkční podporu.
• Platba požadavku PATCH není přímočará jako u požadavku PUT. např.

  HTTP GET /users/1

  produkuje následující odpověď:

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

  Ukázkový požadavek na opravu pro aktualizaci e-mailu bude vypadat takto:

  HTTP PATCH /users/1

  “ }
  ]

Mohou existovat následující možné operace jsou podle specifikace HTTP.

},
{ "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" }
]

Metoda PATCH nenahrazuje metody POST nebo PUT. Použije spíše delta (rozdíl) než nahrazení celého prostředku.

Souhrn metod HTTP pro rozhraní API RESTful

Následující tabulka shrnuje použití výše uvedených metod HTTP.

Glosář

Bezpečné metody

Podle specifikace HTTP by se metody GET a HEAD měly používat pouze pro načtení reprezentace zdroje – a neaktualizují/neodstraňují zdroj na serveru. O obou metodách se říká, že jsou považovány za „bezpečné“.

To umožňuje uživatelským agentům reprezentovat ostatní metody, jako jsou POST, PUT a DELETE, jedinečným způsobem tak, aby byl uživatel upozorněn na skutečnost, že je požadována možná nebezpečná akce – a mohou aktualizovat/smazat prostředek na serveru, a proto by měly být používány opatrně.

Idempotentní metody

Termín idempotentní se používá komplexněji pro popis operace, která přinese stejné výsledky, je-li provedena jednou nebo vícekrát. Idempotence je užitečná vlastnost v mnoha situacích, protože znamená, že operaci lze opakovat nebo zkoušet tolikrát, kolikrát je třeba, aniž by došlo k nechtěným účinkům. U neidempotentních operací může být nutné, aby algoritmus sledoval, zda operace již byla provedena, nebo ne.

Ve specifikaci HTTP jsou metody GET, HEAD, PUT a DELETE prohlášeny za idempotentní metody. Ostatní metody OPTIONS a TRACE NESMÍ mít vedlejší účinky, takže obě jsou ze své podstaty také idempotentní.