Srdceryvný příběh aneb Základy REST API POLOPATICKY

Náš příběh začíná v době, kdy byl našemu týmu předán požadavek na propojením s jistým systémem. Dodavatel potvrdil, že naimplementuje REST API dle našeho návrhu. A týmu vypukly architektonické orgie.

Zatímco já pročítal všechny moudra o tom, jak navrhnout REST API, kolega se stal fanouškem dokumentačního nástroje Swagger a snažil se poznat všechny jeho možnosti. Provedli jsme tři revize API s několikadenním odstupem. Dokument, který jsme předávali, byl, řečeno slovem moderním, vymazlený.

Existuje-li aplikace, která oplývá ochotou sdílet data s někým konkrétním nebo dokonce s celým světem, dělá to pomocí aplikačního rozhraní. Aby se obě strany domluvily, je zapotřebí se shodnout na komunikačním protokolu. Samozřejmostí je autentizace a autorizace, bezpečnost atd.

Čili vlastník dat vás autorizuje pro přístup do jeho systému pomocí API a je jen na něm, co vám v něm dovolí dělat. Typické je čtení dat, ale i zápis či mazání.

Vnímavý čtenář by mohl prohlédnout nahozenou udičku a poznamenat, že REST API je právě onen zmiňovaný protokol. Není. Nebo je? Je a není? Ano i ne?

REST API totiž tak úplně nedefinuje, jaká data v jakém formátu budou rozhraním putovat. Co tedy definuje?

REST API je architektonický styl vyvinutý souběžně s protokolem HTTP (jak uvádí Wikipedia), a tudíž je zřejmé, že je to API, které je provozováno na webových serverech. REST API tedy definuje endpointy a akce, neboli metody, které lze s nimi provádět.

Endpointy REST API jsou prostými webovými adresami (URL), které obsluhuje webový server. Budeme-li například od systému žádat data o dojivosti mulfonů, získáme je na adrese http://muflochovatel.cz/mufloni/dojivost. Ještě lépe by adresa vypadala jako mufloni/1, kde se dočteme všechny informace o muflonovi číslo 1, a to včetně dat o jeho dojivost. Neboli v hantýrce "zavoláme endpoint".

Endpointy jsou vždy nazvány podstaným jménem. To jest, není možné, aby existoval endpoint "vytvoř" nebo "smaž". Zároveň by název endpointu měl být vždy v množném čísle a z praktických důvodů nejlépe anglicky. Letmým pohledem do slovníku zjišťuji, že anglicky se mufloni nazývají mouflons. Vida, to se hodí.

Druhá část dotazu se nazývá metodou. Jedná se o volbu akce, která se má provést a která je zároveň namapovaná na metody HTTP. Typickou sadou akcí je Vytvoř/Čti/Uprav/Smaž, což se označuje anglickou zkratkou CRUD (Create/Read/Update/Delete). Je o poznání lepší než VČUS.

Protokol HTTP, který tak rádi používáváme ke komunikaci na internetu, ovšem žádné VČUS, pardon, CRUD, nedefinuje. Pak tedy HTTP metoda POST zastupuje akci Vytvoř, metoda GET zastupuje akci Čti, metoda PUT zastupuje Uprav a konečně metoda DELETE prostě maže.

A nyní máme zhruba vše, co potřebujeme vědět o REST API. Akce GET zavolaná nad endpointem

vrátí informace o muflonovi číslo 1

vytvoří nový záznam o muflonovi (samozřejmě je třeba poslat ještě příslušná data)

nám umožní změnit data uložená k muflonovi číslo 1 a konečně

muflona číslo 1 nadobro smaže.

A na okraj mohu uvést malou REST API anekdotu, jelikož pozorný čtenář je již natolik informován, aby ji pochopil:

Tento endpoint nebývá totiž zpravidla implementován, jelikož by sloužil k odstranění všech muflonů (ze systému). Haha.

Další metody se využívají ve speciálních případech a jejich použití si doplní laskavý čtenář sám.

Jak vidno, stále ještě nebyla řeč o protokolu, poněvadž pravidla pro definici protokolů... protokolem nejsou. Jsou to prostě ... pravidla.

Jako komunikační protokol se používá (mimo jiné) JSON. A zkušení implementátoři REST API radí, aby data přenášena v JSONu byla co nejjednodušší, nejprostší, tj. bez zabalení do nadřazených struktur, bez redundance dat atd. To umožní, že pavučinami internetu putuje jen to nejnutnější množství dat. Bereme si to k srdci.

Nuže, pokračujme v našem příběhu. Na základě výše zmíněných pravidel jsme připravili specifikace, dodefinovali strukturu přenášených dat v JSON, datové typy, chybové stavy a tak dále.

Když ovšem došlo na implementaci dodavatelem, zjistili jsme, že REST API se nazývá něco jiného, než jak jsme si výše popsali. Jeho endpointy používaly pouze metodu POST; navíc ony endpointy měly neskutečně dlouhé názvy a data byla zabalená do, pro nás, zbytečných struktur. API bylo nepřehledné a názvy endpointů nezapamatovatelné. Elegance a estetika se vytratily. V našem týmu zavládl smutek. Vzlyky byly přerušovány mačkáním popsaných papírů a mazáním tabule.

Ne, takhle smutně ten příběh nemůže skončit. Jak šel čas, vytáhli jsme z šuplíku starou specifikaci, oprášili ji a napsali mezivrstvu neboli adaptér. Jelikož pokud něco nefunguje tak, jak má, vždy pomůže přidat umravňující vrstvu.

Nyní máme elegantní REST API, svět je zase v pořádku a já si uvědomil jednu důležitou věc: REST API nevytváříme z pohnutek technologických, alebrž a nýbrž proto, aby se s ním lidem dobře pracovalo.

Když jsem kolem roku 1993 četl manuál (ano jsem z dob před vynálezem internetu) k programu Calc 602 (pro koho z vás má číslo 602 magický nádech?), narazil jsem na příklady tabulek dojivosti muflonů, což mi na věky uvízlo v hlavě, přestože tento program nakonec smetl větší a mocnější konkurent.

A tímto bych chtěl tedy vzdát hold vývojářům ze Software 602, že v době s minimálním přístupem k informacím dokázali dělat software, vedle něhož mi přijde všechno, co dělám, jak dětská hračka. A také díky za, to že neztratili humor při psaní manuálu.