REST API

404 znamená, že zdroj neexistuje: klient si vyžádal objednávku 999 a žádná taková není. 500 znamená, že se rozbilo něco u vás — spadlo spojení s databází, propadlo null. Ten rozdíl rozhoduje o tom, jestli klient ukáže „objednávku jsme nenašli“, nebo vzbudí pohotovost ve tři ráno.

Nejčastější hřích je vrátit 200 s { error: '...' } v těle. Každá klientská knihovna i každý monitorovací nástroj čte stavový kód a žádný z nich vaše chybové pole nezná. Vracejte správný kód na serveru a klient přestane hádat.

Když dvakrát pošlete stejný PUT, musí zdroj skončit ve stejném stavu, jako když se poslal jednou — PUT celý zdroj nahrazuje, ne doplňuje. Smazání už smazané objednávky může vrátit 404 nebo 204, ale nesmí při tom smazat něco jiného.

Začne to bolet ve chvíli, kdy zasáhne síť. Telefon na 3G odpadne a požadavek zopakuje; když váš delete potichu zvyšuje počítačko, opakování práci udělá dvakrát. Kdekoli je opakování možné, navrhněte operaci tak, aby druhý průchod nic nezpůsobil.

Ať už dáte /v1/ do cesty, nebo použijete hlavičku s verzí, rozhodněte první den. Po prvním externím klientovi je přejmenování pole breaking change; s verzí z něj bude aditivní změna. Verzujte to, co vidí externí klienti, ne endpointy mezi vlastními službami.

Upřímný kompromis: REST sedí na domény tvarované jako zdroje — objednávky, zákazníci, dokumenty. U jednoho příkazu, který běží dvě minuty a hlásí průběh, se lépe chová POST, který vrátí id úlohy a endpoint se stavem, než modelování „aktualizace zdroje“.