Šis laikam ir no tās sērijas, kad ar aizdusu raksti, raksti, jo galvā ir baisi forša un lieliska doma, bet tad saproti, ka uz virtuālā papīra nemaz tik naski neliekas. Parasti tas paliek melnrakstos. Šoreiz nolēmu nedaudz piepucēt un saglabāt publiskā vietā.

2000. gadā kāds Roy Thomas Fielding publicēja savu doktora disertāciju "Architectural Styles and the Design of Network-based Software Architectures". Pati disertācija ir par vienotu veidu kā izprast un izvērtēt dažādu datortīkla aplikāciju arhitektūras. Kā case study Fīldings nolēma paņemt WWW, jeb REST. Un tā apraksts aizņem tikai vienu nodaļu no sešām.

Patiesais stāsts ar REST piemēru bija tas, ka tādējādi Fīldings nodemonstrēja vispārējo tā brīža WWW arhitektūru, hiperteksta nozīmi, kā arī tā panākumu atslēgu. Viņš neizgudroja REST.

Tas varbūt ir diezgan interesanti - lasīt par agrīno webu (HTTP + HTML) tik akadēmiskā formātā. Bet tanī pat laikā, tas mirklis, kad saproti, ka REST ar mūsu API nav absolūti nekāda sakara, bija maķenīt patīkami atsvaidzinošs.

Tur minētās tēzes diezgan bieži ieklīst manās pārdomās par dažādu sistēmu vai risinājumu dizainiem. Jo labi saprotamai sistēmai pamatā ir vienkārša arhitektūra. Vai arī, ja tā ir sarežģīta, tad saskarnes ir maksimāli triviālas un pašsaprotamas.

Fīldings savā disertācijā aprakstīja sešus pamatprincipus, kuri tika iestrādāti pašā HTTP kā transportā, HTML kā medijā un hipersaitēs kā norādēs. To visu lasot ieteicams ir padomāt par to, cik ļoti modernie steki to visu nereti vēlas pārkāpt.

1. Klienta-servera arhitektūra ar mērķi nodalīt klientu no servera tiktāl, ka katrs no tiem var attīstīties neatkarīgi. Serveris nodrošina datu glabāšanu un biznesa loģiku, bet klients - saskarni un lietotāja stāvokli.
2. Stāvokļneatkarība? Angliski - statelessness. Katrs pieprasījums uz serveri un atbilde no tā satur visu nepieciešamo informāciju, lai klients spēja savā pusē uzturēt nepieciešamo sesijas stāvokli. Serveris sesijas stāvokli neglabā. Piemēram, sesiju kūkiji šo principu salauž. Interesanti, ka JWT to nesalauž, jo sesijas stāvoklis ir pie klienta un pieprasījums ietver visu nepieciešamo informāciju, lai serveris varētu sniegt informētu atbildi.
3. Katram resursam ir jādefinē vai tas ir kešojams un kā, kā var tikt pie tā svaigākās versijas, utt. Tas ir "iecepts" HTTP protokola keša kontroles hederos.
4. Viendabīga saskarne. Saskarnei ir jābūt tādai, lai tai varētu piemērot visvienkāršāko iespējamo arhitektūru. Šis laikam ir vissvarīgākais.
   • Resursiem jābūt viennozīmīgi identificējamiem (piemēram, dokumentam vienmēr būs adrese /document/123).
   • Darbības un manipulācijas ar resursiem notiek tikai caur to reprezentāciju. Tas nozīmē, ka klients, saņemot to pašu dokumentu, saņem arī informāciju kādas darbības ar to ir pieejamas. Nekas netiek pieņemts par pašsaprotamu. HTML gadījumā tās ir formas.
   • Jebkuras manipulācijas notiek, pārsūtot jauno reprezentāciju. Klients pieprasa esošo, izmaina, nosūta serverim. Un nekā citādāk. Dzēšanai tas arī strādā, jo jaunā reprezentācija ir 'neeksistējošs', jeb null.
   • Runājot par iespējamajām manipulācijām. API gadījumā tas reti tiek izmantots, jo klientam ir jāzin - kādas HTTP metodes kad ir jāizmanto. Bet REST nosaka, ka šai informācijai ir jānāk no servera. Teorētiski tam derētu OPTIONS, bet paceļ roku - kurš to nodrošina visiem endpointiem? :D Un savā ziņā tas ir out-of-band - kad jāveic papildu manipulācijas, lai noskaidrotu to, kas jāuzzin no resursa paša.
   • Tas, ko saņem klients, ir resursa reprezentācija, nevis pats resurss. Klients var palūgt un serveris var spēt piegādāt to pašu resursu citā formātā (JSON dokuments, XML dokuments, bildīte, Word fails, utt)
   • Reprezentācijai ir jāsatur gan paša resursa dati, gan tā metadati.
   • Katram ziņojumam ir jāsatur visa nepieciešamā informācija, lai to varētu saprast. Atkal - nekas nav pašsaprotami. Šis ir HTTP protokola pamatā. Metodes (GET, POST, PUT, utt), vienošanās par satura veidu (Content-Type, Accept hederi). Respektīvi - visam kontekstam, kurš nepieciešams, lai ziņojumu saprastu, ir jābūt pašā ziņojumā.
   • Un pēdējā laika baisākais akronīms - HATEOAS (Hypermedia as the Engine of Application State). Serveris piedāvā klientam saites, kuras norāda to, ko ar to resursu var vispār izdarīt.
5. Slāņi. Klientam nav obligati jāspēj pateikt vai tas saņem informāciju no starpniekservera vai pa tiešo no oriģinālservera. Lai tur pa ceļam ir miljons API vārteju, reverso proxy serveru, CDNu, slodzes dalītāju un WAFu. Klientam vienalga.
6. Un vienīgā neobligātā prasība - serveris var piegādāt arī kodu, kuru klients var palaist, lai viss būtu frošāk. Tā varētu būt Java apleta formā deviņdesmitajos vai JavaScript formā šodien.

Lai aplikācija būtu atbilstoša REST, tai jāatbilst pieciem pirmajiem punktiem. Sestais ir neobligāts.

Tāpēc mēs tos API arī saucam par RESTful :) Tie atbilst pamatprincipiem, bet vairums no populārākajām specifikācijām atkāpjas no viena vai vairākiem punktiem.

JSON:API, piemēram, ir diezgan strikts piekritējs visam, ko Fīldings aprakstīja. Ar mazu atšķirību tanī, ka dod iespēju veikt masveida darbības caur vienu endpointu.

JSONLD neseko īsti HATEOAS principam, jo lai arī saites dokumentos eksistē un ir pats pamatu pamats šai specifikācijai, tās neapraksta darbības. Tas vairāk fokusējas uz reprezentācijas pusi, ne manipulācijām.

Mūsdienās mēs uz REST skatāmies kā uz pamatu API būvēšanai, bet ironiskā kārtā REST API biežāk nekā retāk nemaz neseko šiem principiem. Mūsdienās tas vairāk ir HTTP RPC, kur klientam ir jāzin - ko izsaukt, kā izsaukt un kā vispār kaut ko atrast.