Jak se peče restovní API v Symfony

Publikováno: 23.01.2017

Jsme tu všichni hrdě odkojení nettisté. A pak to přišlo, vesmír se sesypal jak domeček z grafických karet, do kanceláře vtrhne náš šéf, tedy (z logiky věci) ten nejmoudřejší, a zařve: “Co když Davida Grudla přejede tatrovka? A to je dost pravděpodobný… Co s náma proboha bude? S přejetým Nette to nikdy nespíchnette…”

A tím to začalo…

Volba nového PHP frameworku padla jednomyslně na Symfony. Pečeme u nás aplikace jak pro VSHosting (čímž jsou ty internety zas o něco lepší), tak pro jeho klienty. Jedna z nadcházejících výzev je chystané REST API pro nový ticketovací systém. A na to je třeba mít kudly pořádně nabroušené a výpeky božsky redukované.

Jen pro představu, jaká nálož bude v pekáči: verzování s maximálním znovupoužitím již napsaného (zbytečné psaní je zbytečné) a kompatibilitou dopředu, dozadu i nahoru a dolů, strojové generování dokumentace pomocí Swaggera (bývá zvykem, že hlavní a jediná dokumentace se nachází za nefunkčním odkazem, ale není to úplně ono), použití Elasticu (megaúložiště, do nějž se replikuje databáze, aby čtení dat včetně fulltextového vyhledávání v milionech záznamů bylo v řádech desítek milisekund, tedy nechutně rychlé), automatizovaná validace vstupů (důvěřujeme, ale prověřujeme) včetně hlášení všech chyb najednou (čtenář se nesmí napínat, aby nedostal infarkt), automatizovaná validace výstupů (nevěříme ani sami sobě), autonaplnění výstupního objektu daty z Elasticu atd. atd. atd.

Symfony pomůže v mnohém. Grunt nám dá FOSRestBundle, který zajistí základní routování (včetně typu requestu – GET, POST, PUT ad.) dle názvu metody v controlleru a naplnění vstupního objektu příchozími daty.

Pokud použijeme základní symfonní JSON response, můžeme z ní trochou ladných pohybů vykouzlit jak success API response (která přijme výstupní DTO objekt, zvaliduje a šup s ním ven jako JSON), tak error API response (která přijímá všechny API exceptions a z nich automaticky sestaví JSON odpověď včetně HTTP statusu, kódu chyby, chybové hlášky a případně dalších doplňujících dat). Pokud jsme líní a nechceme dokola psát error response do každé metody každého controlleru (a do většiny metod vícekrát), navěsíme na událost typu EXCEPTION listener, v němž danou chybu zpracujeme, a v controllerech pak stačí sázet API výjimky jak jahody do koláče.

S validacemi vstupu nebo výstupu pomůže symfonní validátor, který pomocí jednoduchých anotací zvládá i hutnější validace, nejen obvyklý basic jako datový typ, čas, email… ale také rozsah, porovnávání, IBAN 🙂 a další. Pro vyšší výkon lze samozřejmě validace zamrazit do keše a schovat na příští sezónu. Validaci vstupu stačí provést v rámci requestu FOSRestBundle, a pokud to chceme ještě potunit a nebaví nás sbírat $validationErrors v každé metodě každého controlleru, stačí na request navěsit listener a validaci zpracovat v něm.

Pro serializaci pomůže JMSSerializerBundle, který vstupní JSONy “přeleje” do předem definovaných DTO objektů a výstupní DTO objekty zas převede na JSON, který, čerstvě upečený, vyjede uživateli. Pravidla se definují rovněž anotacemi a k dispozici je řada užitečných fičur, např. parametr obsažen až od určité verze API, automatické přejmenování atd.

Domluvu s Elasticem zajišťuje ElasticsearchBundle, který funguje v principu podobně jako Doktrína: dokumenty v Elasticu jsou reprezentovány entitami v PHP aplikaci a ve výkonném kódu se plní jako obraz dat, který bude uložen v Elasticu samotném. Podporovány jsou samozřejmě i nested objects, takže do Elasticu lze narvat entitu i s jejími dětmi a dalšími příbuznými.

Pro geerování swaggří dokumentace je použit Symfony NelmioApiDocBundle, který (jak jinak než z dokumentačních komentářů) strojově vygeneruje swagger JSON. Anotátor umí mimo jiné roztřídit endpointy do skupin, takže privátní část API nebude ve veřejné dokumentaci, ale třeba také endpoint pouze pro API verze 2 nebude v dokumentaci pro verzi 1.

Závěr všeho se, jak už to tak bývá, ukáže až na závěr. Snad to bude dost propečené a nová aplikace přinese zákazníkům i klukům z technické podpory radost a smích.

Vývojový tým VSHosting

Leave a Reply

Your email address will not be published. Required fields are marked *