Programmeerimisliides ehk API on moodus, mis võimaldab kahel rakendusel omavahel andmeid vahetada, kusjuures need rakendused võivad olla kirjutatud täiesti erinevates keeltes.

Veebiteenus on selline API, mis kasutab HTTP protokolli nagu veebiserveridki (Apache, Nginx) brauseritega suheldes (Firefox, Google Chrome), mistõttu saab neid ka brauseriga mõningasel määral (ainult GET päringute osas) kasutada.

Kaks kõige levinumat viisi veebiteenuse tegemiseks on SOAP ja REST.

Mis on nende erinevus? SOAP on standard, mis kirjeldab sõnumite vormingut, mida veebiteenus ja selle klient üksteisega vahetavad. REST on aga kogumik mittekohustuslikke soovitusi (best practices), kuidas hästikäituvad rakendused võiksid andmeid üle veebi (see tähendab kasutades HTTP protokolli) vahetada ja igal veebiteenuse ehitajal on RESTist oma spetsiifiline nägemus, kuigi suures osas nad kattuvad.

2. SOAP

SOAP (lühend on tuletatud fraasist Simple Object Access Protocol, kuid versioonist 1.2 on öeldud, et SOAP ole enam akronüüm, vaid lihtsalt nimi) on natuke vanem veebiteenuste loomise viis, mis leidis varem laialdast kasutust. SOAP on väga ulatuslik, kuid keeruline standardite kogum. Nimelt Microsofti meeskond, kes kavandas SOAPi, tegi selle äärmiselt paindlikuks, et see võimaldaks suhtlemist nii privaatvõrkudes, internetis kui ka isegi elektronposti vahendusel. 

UDDI ja WSDL

SOAP-i esialgne versioon oli osa spetsifikatsioonist, mis sisaldas ka Universal Description, Discovery and Integration (UDDI) nimelist standardit, mis oli mõeldud SOAP teenuste leidmiseks ja Web Services Description Language (WSDL), mis oli mõeldud SOAP teenuste dokumentatsiooniks. UDDI ei levinud nii laialdaselt kui selle loojad lootsid ja 2006. aasta jaanuaris teatasid IBM, Microsoft ja SAP, et nad sulgevad oma avalikud UDDI serverid. 2007. aasta lõpus sulges ka UDDI-d määratlev rühm oma uksed ehk UDDI-t enam edasi ei arendatud ja 2010. aasta septembris teatas Microsoft, et nad eemaldavad UDDI teenused Windows Serveri operatsioonisüsteemi tulevastest versioonidest.

SOAP sätestab sisuliselt ümbriku ehk XML struktuuri veebiteenustega andmede vahetamiseks. Arhitektuur ise on loodud selleks, et aidata kaasa erinevate operatsioonide sooritamisele tarkvaraprogrammide vahel. Programmide vaheline suhtlus toimub tavaliselt XML-põhiste päringute ja HTTP-põhiste vastuste kaudu. Enamasti kasutatakse HTTP suhtlusprotokolli, kuid võib kasutada ka muid protokolle.

SOAP-sõnum sisaldab mõningaid kohustuslikke osi, nagu ENVELOPE, HEADER, BODY ja FAULT. ENVELOPE objekt määratleb XML-sõnumi taotluse alguse ja lõpu, HEADER sisaldab kõiki serveri poolt töödeldavaid päiseelemente ja BODY sisaldab ülejäänud XML-objekti, mis moodustab taotluse. FAULT-objekti kasutatakse vigade käsitlemiseks.

REST veebiteenusega saab suhelda kasutades HTTP protokolli. Antud joonisel esitab REST veebiteenus küsitud andmete hetkeoleku JSON formaadis.

4. Mida tähendab RESTful?

Enamik API-sid maailmas on RESTful, mis tähendab, et nad järgivad suures osas teatud reeglite või õieti piirangute kogumit, mida tuntakse kui Representational State Transfer ehk REST, mis on alates 2000. aastate algusest olnud de facto standard API-de arendamisel. De facto sellepärast, et ametlikult ei ole REST standard, vaid Roy Fieldingu poolt doktorikraadi väitekirjas kirja pandud parimate praktikate kirjeldus, millele on aegade jooksul lisandunud ka teisi häid tavasid.

5. Kuidas valida SOAPi ja REST-i vahel?

SOAPi ja RESTi vahel tuleb valida vastavalt projekti nõuetele. Mõnedel programmeerimiskeeltel (nt Java) on väga hea SOAP tugi ja selle kasutuselevõtt on lihtne. Muus keeles pole see nii lihtne (nt Javascriptis pole keelde sisse ehitatud tuge ja tuleb kasutada väliseid teeke, mis on kohmakas). Samuti on REST väga palju rohkem levinud ja suvalisel arendajal on suure tõenäosusega RESTist mingisugune arusaam juba olemas, mistõttu on üldjuhul REST parem valik.
Võrreldes RESTiga on SOAP kindlasti keerulisem ja kasutab rohkem andmemahtu, aga SOAP pakub ka eeliseid: 

• transpordist sõltumatu (REST vajab HTTP-d, sest kasutab HTTP verbe käskudena ja URL-e andmekollektsioonidele viitamiseks, aga SOAPi puhul on kogu info XMLi sees, mis on POST päringu keha sees, aga tegelikult pole vahet, mis meediumi vahendusel XML-ide vahetamine toimub, kasvõi tuvipostiga), 
• töötab hästi hajutatud ettevõtluskeskkondades (REST API server vajab otseühendust kliendiga, aga SOAPiga pole vahet, mitmest kohast XML dokument enne serverini jõudmist läbi käib (kasvõi läbi pastebin.com-i), 
• on standardiseeritud (kõik on standardiga paigas, kuidas implementeerida, aga RESTi puhul peab disainiotsuseid ise tegema ja guugeldama neid, süvenedes arendajate pikkadesse filosoofilistesse väitlustesse, kas nii või naa oleks parem),
• ws-standardid (valmisarendatud sõnumikomplektid tüüpilisteks stsenaariumiteks nagu nt sisselogimine, et neid ise leiutama ei peaks).
• sisseehitatud veahaldus ja automaatika (teatud tasuliste toodete kasutamisel)

RESTil ei ole nii palju valmisfunktsionaalsust, ent võrreldes SOAPiga on tal järgmised eelised:

• paindlik ja lihtne kasutada (kui mõni RESTi tingimustest ei meeldi, ei pea seda kasutama, kuigi siis öeldakse, et sinu REST teenus ei ole RESTful)
• veebiteenusega suhtlemiseks ei ole vaja lisatarkvara, sest HTTP päringute tegemise võimalus ja JSON tugi on pea kõigis keeltes sees olemas.
• väiksem õppimiskõver (põhimõtteliselt töötab REST API server nagu tavaline veebiserver, väljastades HTML asemel JSONit)
• parem jõudlus / optimaalne võrguliikluse kasutus (SOAP kasutab kõikide sõnumite jaoks rangelt XML-i, mis on äärmiselt jutukas formaat ja kulutab info edastamiseks väga palju baite, RESTiga kasutatakse peamiselt JSON formaati, mis on palju kompaktsem ja lihtsam lugeda ka. Lisaks on RESTi puhul käsk HTTP meetod ja parameetrid URL-is, SOAPil on aga alati POST meetod ja sama URL ning käsk ja parameetrid on päringu kehas XML elementide sees), 
• REST on disainifilosoofiliselt lähemal teistele veebitehnoloogiatele (kasutab HTTP enda meetodeid käskudena ja HTTP URL-i URI-na)

6. Kuidas erineb URI RESTis ja SOAPis?

RESTful API puhul on serveri andmebaasis paiknevaid andmed tehtud API kaudu kättesaadavaks nn ressursside või kollektsioonidena. Igale kollektsioonile ehk ressursile on eraldatud omaette URL. Tehniliselt nad pole küll mitte URL-id, vaid URI-d (unified resource identifier). Mõte on selles, et nad eristavad eri tüüpi andmeressursse serveris. Näiteks raamatupidamistarkvara REST API-l võib olla olemas URI-d /invoices, /accounts, /payments, /orders. Need peavad olema nimisõnad ja mitmuses. Näiteks ei sobi /car ega /getCar, vaid /cars. Sisselogimiseks on kollektsioon /sessions, kuhu elemendi (sessiooni) lisamisel on kasutaja sisse logitud. SOAPis sõltub URI aga sellest, millist bindingut kasutatakse. Binding seob millegi millegagi. Antud kontekstis on mõeldud seda, et SOAPi meetodid saab siduda HTTP meetoditega, kui kasutada selleks spetsiaalselt väljatöötatud SOAP-i laiendust nimega SOAP HTTP Binding. Näiteks /accounting-web service.

1.2 Andmete lugemine ja töötlemine JSON andmevahetusformaadist

Mis on JSON?

JSON struktuur

JSON on andmevahetusformaat, mida on lihtne analüüsida ja genereerida. JSON on objekti andmete kirjeldamiseks JavaScript’is kasutatava süntaksi laiendus. Ometi ei ole see piiratud JavaScript’iga kasutamisega. See on tekstivorming, mis kasutab andmete kaasaskantavaks esitamiseks objekti- ja massiivstruktuure. Kõik kaasaegsed programmeerimiskeeled toetavad JSON andmestruktuure, mis teeb JSONi keelest sõltumatuks. JSON kasutus on ülimalt populaarne REST API-de puhul.

JSON-objekti struktuur on järgmine:

• looksulgudes {} hoitakse objekte, mis on komadega eraldatud andmed võti:väärtus formaadis;
• võtmed on alati ümbritsetud jutumärkidega (erinevalt JavaScriptist);
• võtmete kaudu saab objektist konkreetseid andmeid küsida;
• nurksulgudes [] hoitakse massiive, mis võivad sisaldada 0 kuni lõpmatus (kuni mälu jätkub) arvul elemente, mis võivad olla stringid, objektid, teised massiivid või muud sorti andmed, mida JSON toetab;
• kui väärtus on string, on ta ümbritsetud jutumärkidega.

Näide JSON struktuurist (kompaktsel kujul)

Ühe objekti sees on teine objekt.

Mitu objekti, mille väärtusteks on objektid.

Objektis Valve pesitseb mitu objekti massiivi sees

Objektid ja massiivid on väärtused, mis võivad sisaldada teisi väärtusi, seega on JSON-andmetega võimalik piiramatu pesastamine (nesting). See võimaldab JSON’is kirjeldada enamikku andmetüüpe, alates tabelitest kuni veelgi keerulisemate andmetüüpideni.

JSON andmetüübid

Nüüd, kui oled näinud JSON’i struktuuri, oled tutvunud mitmete selle andmetüüpidega. Siin on täielik loetelu JSON’i andmetüüpidest:

• string – Sõnaline tekst, mis on ümbritsetud jutumärkidesse.
• number – Positiivsed või negatiivsed täisarvud või ujukomaarvud.
• objekt – Võtme ja väärtuse paar, mis on ümbritsetud kõverate sulgude sisse.
• array – Massiv, kuhu saab pesitseda mitmeid JSON-objekti kogumeid.
• boolean – Väärtus true või false ilma jutumärkideta.
• null – Näitab andmete puudumist võtmeväärtuspaari puhul, mida esitatakse kui “null” ilma jutumärkideta.

1.4 Veebiteenuse optimeerimine ja andmete puhverdamine ning dubleerimine

Andmete puhverdamine (ingl data caching) on protsess, mis salvestab andmeid või faile ajutisse salvestuskohta ehk vahemällu, et neile saaks kiiremini ligi pääseda. See salvestab andmeid tarkvararakenduste, serverite ja veebibrauserite jaoks, mis tagab, et kasutajad ei pea veebilehe või rakenduse laadimise kiirendamiseks iga kord teavet alla laadima.
Andmete dubleerimine (ing data replication) on protsess, mille käigus tehakse andmetest koopiaid ja hoitakse neid varundamise eesmärgil eri kohtades, kas samas süsteemis, füüsilises/virtuaalses serveris või pilvepõhiselt.

Andmete dubleerimine kasutatakse, et:

• parandada andmete kättesaadavust
• suurendada andmetele juurdepääsu kiirust
• parandada serveri jõudlust
• andmeid taastada

localStorage and sessionStorage

localStorage ja sessionStorage võimaldavad salvestada võtme-väärtuse paare lokaalselt. SessionStorage’i puhul andmed säilivad lehe uuendamisel ja localStorage’i puhul kuni kasutaja kustutab brauseri vahemälu käsitsi või kuni veebirakendus kustutab andmed.

Soorita harjutused 3 ja 4.

Küpsised

Kui klient saadab serverile HTTP päringu, luuakse serveri TCP pordiga korraks sessioon, mis on kahesuunaline sidekanal, kuid HTTP on tehtud nii, et esmalt saadab klient päringu ja siis server vastab sellele ning katkestab kohe ühenduse ära. Kui klient soovib pärast seda teha uue päringu, peab ta looma uue TCP ühenduse aga serveri poolelt on näha ainult kliendi IP aadress ja port. Aga sama IP aadressi taga võib olla mitu klienti ja klient võib oma IP aadressi vahetada (nt WiFi ühenduselt 4G peale üle minnes või vastupidi). Seega kui klient uue päringu teeb, pole serveril aimugi, kas see on see sama klient või mitte.

Küpsised (ingl cookies) on väikesed nimi=väärtus paarid, mida veebiserver saab kliendile saata ning mida klient võib serverile järgneva(te) päringu(te)ga tagasi saata, kuni küpsis aegub.

Soorita harjutus 5.

Küpsised võimaldavad serveril eristada kliente üksteisest ja võimaldavad sisselogimisfunksionaalsust, saidi eelistuste salvestamise funktsionaalsust, ostukorvi jms, mis eeldab, et server tunneb kliendi ära.

Kuidas localStorage töötab?

Kui küpsised on andmed, mis liiguvad päringute päistes, siis localStorage on brauseri funktsionaalsus, mis võimaldab kliendi poolsel Javascriptil (see JS, mis jookseb brauseris, mitte serveris, kuid mille server on üldjuhul kliendile käivitamiseks saatnud) kasutada kohalikku kõvaketast, et vajalikke andmeid seal hoida. Näiteks puhverdamise eesmärgil.

Oluline on see, et kui localStorage’isse midagi panna, siis teiste domeenide serveritest (või isegi samal domeenil, aga teise pordi otsas ja isegi http vs https on erinevad serverid localStoragei jaoks) ei saa seda lugeda. Piltlikult öeldes näiteks Facebook ei saa lugeda, mida Gmaili veebirakendus brauseri localStorage’isse pani.

LocalStorage objektil on viis meetodit:

• setItem(): Võtme ja väärtuse lisamiseks localStorage’isse
• getItem(): localStorage’ist objekti väärtuste saamiseks
• removeItem(): Elemendi objekti võtme järgi localStorage’ist eemaldamiseks
• clear(): kogu localStorage’i tühjendamiseks
• key(): Antud number localStorage’i võtme leidmiseks

Näide

Allolevalt toome näite, kuidas localStorage’it saab andmete puhverdamiseks kasutada:

Selgitus:

• Real 1 kontrollitakse, kas localStorage’is on miskit võtme widgetsCache all
• Rida 2: kui localStorage’is oli selle võtme all miskit, antakse see widgetsCache’ile väärtuseks. Enne väärtustamist tehakse eeldus, et tegemist on JSON formaadis tekstiga ja teisendatakse see JSON-ist Javascript objektiks.
• Rida 3: kui localStorage’is ei olnud selle võtme all midagi, antakse widgetsCache’ile väärtuseks võrgupäringu tulemusel saadud JSONist parsitud objekt (või mis iganes andmetüüp, mis parsimisel saadi).
• Real 5 salvestatakse widgetsCachei hetkeväärtus localStorage’isse, et seda järgmisel korral ilma võrgupäringut tegemata saaks kasutada.