Jedno z nejdůležitějších témat v souvislosti s vývojem REST API je design. Špatně navržené API má nepříjemné důsledky. Konzumenty nutí používat jej nestandardním způsobem a různě ohýbat nástroje, na které jsou zvyklí. Prodlužuje se doba implementace a vznikají bugy, se kterými implementátor většinou nepočítá. Chybně navržené API zkrátka hází klacky pod nohu konzumentům a vytváří tlak na nápravu. Ta není jednoduchá. API je v již produkčním provozu a jakákoliv změna navenek znamená rozbití již existujících integrací. Časté řešení a zároveň velká past je verzování API. To zvyšuje komplexitu projektů a vede buď k redundanci nebo tvorbě složitých řešení, jejichž devizou jsou neustálé bugy. Jediná cesta ven je navrhnout API co nejlépe již na začátku a následné změny provádět s určitou mírou prevence před potenciálními scénáři.
Jako RESTová API jsou dnes často mylně označovaná všechna API, která jsou založena na protokolu HTTP a přenosovém formátu JSON. Na druhou stranu REST omezení, která byla definována R. T. Fieldingem před dvěma dekádami v podstatě popisují nejen API, ale obecně mnoho běžných WWW stránek. Neexistuje jasná norma, která by rozlišovala správný a špatný návrh API. To znamená, že dobře navržené API je obvykle v gesci architekta. Ten vezme již osvědčené postupy, přileje trochu praxe a výše zmíněné prevence či specifika projektu a na základě těchto a dalších vstupů navrhne design, který s trochou štěstí odolá náporu následných požadavků.
Není složité udělat API restful, je těžké udělat API „správně“. Pojem „správné API“ je ale z logiky věci zcela vágní. Od API očekáváme dvě věci. Jednak umožnit pohodlně konzumovat data klientům a druhak kontinuálně zachovávat zpětnou kompatibilitu. Oba požadavky spolu souvisí, protože bez zpětné kompatibility velmi rychle snížíme komfort při konzumaci. Na druhou stranu zachování kompatibility může být výzva, která nás ve jménu klientského komfortu může stát nadměrné úsilí.
V případě, že API stavíme jako backend pro naše vlastní SPA aplikce, je situace snazší. Jsme totiž tvůrcem i jediným konzumentem. Můžeme si tudíž velmi jednoduše dovolit API přepsat a nasadit jeho novou verzí společně s klientskou aplikací. V případě mobilních aplikací už to není tak jednoduché, protože uživatelé mohou mít nasazené starší verze aplikací a my je nepřinutíme, aby v jeden okamžik použili verzi novou a plně funkční. I případ vlastní SPA aplikace se může rychle změnit. Co když budeme chtít v jeden okamžik data zpřístupnit dalším konzumentům? Na designu REST API zkrátka záleží vždy.
Webinář praktický design REST API
Téma mi přijde natolik zajímavé a důležité, že jsem pro něj nachystal nový webinář. Během něj chci účastníky seznámit s REST principem a více rozvést myšlenky, které jsem nastínil v tomto článku. Na scénářích z praxe vysvětlím, jak nad designem obecně uvažovat a jak hluboko se jím kdy zabývat. Ukážu také sadu praktických „návrhových vzorů“ a osvědčených postupů pro vývoj REST API, které jsem v posledních letech použil. Místo programování se budu převážnou část věnovat zejména návrhu a správné podobě endpointů a vracených struktur. Tématicky se pozastavíme i u trendu tzv. asynchronních API a chybět nebude ani pár tipů pro návrh architektury REST API v ASP.NET Core.
Registrace na webinář je možná zde.