Minulý díl byl věnován nejlepším postupům v tvorbě REST API, které v dnešním díle uvedeme do praxe. Kromě toho se podíváme podrobněji na kešování a zpracování chyb ve frameworku Express. Na konci článku si představíme známý český projekt Apiary, který při práci s API výrazně pomáhá.
Jestli jste někdy řešili nasazování aplikace, asi víte, že všechno odladit může být celkem zdlouhavá záležitost. Dokážete si představit, že na to máte jen týden? Že je to nemožné? Není! Jde to a ani to nemusí být příliš složité.
Reportáž z virtuální konference FOSDEM. Minule jsem popsali Go room, dnes se věnujeme monitoringu a observability.
Mikrofrontendy jsou zajímavá adaptace konceptu microservices pro potřeby frontendového vývoje. Podívejte se, co to v praxi obnáší a proč jsme se v Seznam.cz rozhodli vyvinout náš vlastní microfrontend framework, Merkur.
Zpátky na stromy?
Rozlišovat HTTP metody procedurálně pomocí IFů a porovnávání textových řetězců? Kde to jsme? Totéž podporované MIME typy a vyhazování výjimek. Vždyť tohle jde na jiných platformách krásně deklarativně pomocí pár anotací — a člověk se pak může soustředit na vlastní obchodní logiku. Tohle mi přijde jako krok zpět…
Re: Zpátky na stromy?
Dobrý den,
díky za reakci. V porovnání POST a POT s req.method nevídím žádný problém, přijde mi to v uvedeném případě jako docela srozumitelný zápis. Příchozí data s nastavením Content-Type nebo požadavek na odchozí data v Accept mohou být jen ve formátu JSON, jiný v rámci seriálu podporovat nechci a v zápise req.is(‚json‘) nebo req.accept(‚json‘) taky nevidím problém, opět mi to přijde poměrně srozumitelné.
Pokud jde o řešení chyb, tak by to šlo udělat hezčím způsobem (v posledním odstavci sekce o zpracování chyb je to zmíněno), ale myslím si, že to pro seriál stačí nechat, jak to je. Moje třídy pro reprezentace chyb mají info o odesílaném HTTP stavovém kódu, takže nejprve odchytím je a odpovím uživateli s daným kódem. V druhé části middleware řeším ostatní typy chyb. A jednou z nich je i ValidationError, kterou si odchytím zvlášť a zpracuji. Díky tomu nemusím v controllerech řešit vůbec validaci, ale pokud nastane jakákoliv chyba vč. validace, získám ji v objektu err a zpracuji ji v middleware error.
REST?
Ještě k předchozímu dílu:
„Např. URL pro vygenerování faktury pro objednávku číslo 123 může mít adresu: /example.com/orders/123/generate Akce se bude volat metodou HTTP POST, protože žádná akce GET nesmí data měnit.“
Tím se z toho vlastně stává RPC – už neděláme CRUD operace nad zdroji, ale voláme vzdálené procedury: generujFakturu();
„Chceme-li se odkázat na dokument, který závisí na jiném dokumentu a nemůže existovat zvlášť, přidáme do cesty i rodičovský dokument. Např. varianty produktů nemohou existovat samostatně, takže na variantu s ID 456 produktu ID 123 se můžeme odkázat takto: example.com/products/123/variants/456“
Takže objednávka by měla pak mít URL třeba /customer/123/order/456 nebo výrobek: /supplier/123/product/456 – protože objednávka neexistuje bez zákazníka a výrobek bez výrobce. Nakonec bychom do toho URL mohli zahrnout i další entity, bez kterých by to nemohlo existovat… Což by asi nebylo dvakrát rozumné.
Re: REST?
Počkejte, prosím, ještě tři díly. Po tom následujícím budou dva převážně o js u klienta (AngularJS & Testacular), tím se uzavře část seriálu, kde se vytvářelo prostředí. Hned v tom dalším se vytvoří kompletní rozhraní API pro celý e-shop.
REST vs. RPC
A tam vysvětlíte (mimochodem, musíme si vykat?), jak zavolat proceduru (generování faktury) pomocí CRUD/RESTu?
(ano, vím, že to jde, i jak to jde, ale je to zneužití té technologie resp. použití technologie, která nepasuje na zadání)
Re: REST vs. RPC
Můžeme si samozřejmě tykat:-)
Odpovím úryvkem z knihy REST API Design Rulebook, na kterou jsem v minulém článku odkazoval a kterou považuji za nejlepší zdroj informací o REST.
Controller
A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs. Like a traditional web application’s use of HTML forms, a REST API relies on controller resources to perform application-specific actions that cannot be logically mapped to one of the standard methods (create, retrieve, update, and delete, also known as CRUD).
Controller names typically appear as the last segment in a URI path, with no child resources to follow them in the hierarchy. The example below shows a controller resource that allows a client to resend an alert to a user:
POST /alerts/245743/resend
Re: REST vs. RPC
Chápu, že v praxi se prasí mnohem víc (např. se používají GET metody i pro změny stavu, protože klient prostě nic jiného poslat neumí), chápu i to, že se to směrem k zákazníkovi prezentuje jako REST, protože to teď letí a každý to musí mít. Ale nechápu, proč je potřeba si takhle lhát i v článcích a mezi programátory – copak je tak těžké si přiznat, že REST se nehodí na všechno a ne vše se pomocí něj dá realizovat? Vždyť i tak je to dobrá technologie, jen není univerzální (ale to není žádná). Takže navrhuji tomu (těm procedurálním částem) přestat říkat REST nebo použít nějakou jinou vhodnější technologii pro volání procedur – místo hraní divadýlka a předstírání, že tu jsou nějaké „procedurální zdroje“, a vymýšlení pseudoteorií, které obhájí, že to je ještě REST, abychom nemuseli přiznat, že REST nejde použít na vše.
A to přirovnání k HTML formulářům je naprosto nesmyslné – formulář typicky je CRUD práce se zdrojem, např. to založení objednávky. Případně to není práce se zdrojem (např. složitější vyhledávání nebo zadání parametrů pro výpočet něčeho na serveru – třeba zadáme rozměry a materiály a server nám vypočte cenu), ale tomu zase nikdo (rozumný) neříká REST, protože to REST není a je to normální RPC pomocí HTTP POST a HTML formuláře.
Re: REST vs. RPC
Ok, já mám úplně jiný názor a více už o tom nemá smysl diskutovat;-)
CRUD ⊆ REST
CRUD ⊆ REST.
REST může obsahovat „magii“ v podobě volání procedur, někdy to je vhodné. Na implementaci samotného CRUD stačí nějaká NoSQL databáze, možná CouchDB a nemusí se nic řešit. Protože je ale potřeba nad daty vykonávat netriviální akce, je třeba to „nějak“ udělat a ten název kontroleru na konci URL není zase tak špatný nápad. Ano, má to blízko k RPC, ale neznamená to, že to už není REST. Naopak, to si myslím, že je rozdíl mezi syrovým CRUD a REST, tenhle kousek navíc…
A hlavně REST není standart, není to ani doporučení, REST je styl architektury software a to velice volný, založený pouze na principech HTTP.
Pro ty, kteří chtějí pevnější a typový návrh jsou tu web services popsané pomocí WSDL, WADL nebo RPC protokoly…
Re: REST/CRUD vs. RPC
P.S. ještě citace z článku, který odkazujete v prvním díle:
Pomocí REST lze ovládat i stav aplikace, pokud jej dokážeme popsat takovým způsobem, že si vystačí s modelem „zdroje – CRUD akce“.