API

API ehk programmeerimisliides on mehhanism, mis võimaldab kahel rakendusel omavahel andmeid vahetada, isegi kui need on kirjutatud erinevates programmeerimiskeeltes. Veebiteenus on spetsiifiline API tüüp, mis kasutab andmevahetuseks HTTP protokolli, sarnaselt sellele, kuidas veebiserverid (nagu Apache või Nginx) suhtlevad brauseritega (näiteks Firefox või Google Chrome). Seetõttu saab veebiteenustega mõningal määral suhelda ka brauseri kaudu, eelkõige GET päringute kontekstis.

Oluline on mõista, et kõik veebiteenused on API-d, kuid mitte kõik API-d ei ole veebiteenused. Näiteks Windows API võimaldab kõikidel Windowsi töölauarakendustel kasutada operatsioonisüsteemi sisseehitatud funktsioone, nagu näiteks kasutajale teate kuvamine. Samuti on olemas spetsiaalsed API-d riistvaraga suhtlemiseks, nagu OpenGL, Metal või Direct3D.

SOAP ja REST

SOAP on standard, mis määratleb sõnumite vormingu, mida veebiteenus ja selle klient omavahel vahetavad. REST seevastu on kogum soovituslikke juhiseid (best practices) selle kohta, kuidas rakendused võiksid efektiivselt andmeid üle veebi (kasutades HTTP protokolli) vahetada.

Kuigi REST ei ole range standard nagu SOAP ja annab veebiteenuste loojatele rohkem paindlikkust, on RESTi rakendamisel siiski üldiselt aktsepteeritud tavad, mida enamik arendajaid järgib, kuigi igal arendajal võib olla RESTist oma spetsiifiline tõlgendus.

SOAP

SOAP (Simple Object Access Protocol) on vanem veebiteenuste loomise meetod, mille töötas välja Microsoft. Algselt oli SOAP akronüüm, kuid nüüd on see lihtsalt nimi. SOAP on paindlik ja keeruline standard, mis võimaldab andmete vahetamist XML-põhiste sõnumitega, kasutades enamasti HTTP protokolli, kuid ka teisi protokolle.

SOAP-sõnum koosneb põhiosadest: ENVELOPE (sõnumi piirid), HEADER (päiseelemendid), BODY (põhisisu) ja FAULT (vigade käsitlemine). Lisaks SOAP-ile kuulusid varajasse spetsifikatsiooni ka UDDI teenuste leidmiseks ja WSDL teenuste dokumenteerimiseks, kuid UDDI arendamine lõpetati 2007. aastal.

REST

REST (Representational State Transfer) on veebiteenuste arhitektuuristiil, mitte protokoll ega standard. See määratleb tingimused, millele hästi kavandatud veebiteenus peaks vastama, kuid ei määra sõnumi sisu. REST võimaldab kahel tarkvaraprogrammil suhelda, kasutades HTTP-protokolli ja URI-sid (Uniform Resource Identifier) ressursside viitamiseks. REST kasutab HTTP-verbe nagu GET, POST, PUT ja DELETE, ning andmevahetuseks formaate nagu XML, HTML või eelistatult JSON.

REST on lihtsam ja arendajasõbralikum kui SOAP, olles vähem keerukas ja sõnarikkam. Tänu sellele on REST muutunud de facto standardiks avalike API-de loomisel.

RESTful

Enamik API-sid on RESTful, järgides REST-i põhimõtteid, mis on alates 2000. aastate algusest muutunud API-de de facto standardiks. Kuigi REST ei ole ametlik standard, põhineb see Roy Fieldingu doktoritöös kirjeldatud parimate praktikate kogumil, mida on aja jooksul täiendatud.

Kuidas valida SOAPi ja REST-i vahel

SOAPi ja RESTi valik sõltub projekti nõuetest. Mõned programmeerimiskeeled, nagu Java, toetavad SOAP-i hästi, samas kui teistes, nagu JavaScript, on SOAP-i kasutamine keerukam. REST on laialdasemalt levinud ja arendajatele paremini tuttav, muutes selle sageli eelistatavamaks.

SOAP on keerulisem ja kasutab rohkem andmemahtu, kuid pakub eeliseid:

• Transpordist sõltumatus: SOAP töötab erinevate protokollidega, kuna kogu teave on XML-is, samas kui REST vajab HTTP-d.
• Hajutatud keskkonnad: SOAP ei nõua otsest ühendust kliendiga, REST aga vajab.
• Standardiseeritus: SOAP on rangelt standardiseeritud, REST nõuab rohkem disainivalikuid.
• WS-standardid ja veahaldus: SOAP pakub valmisarendatud sõnumikomplekte ja sisseehitatud veahaldust.

REST-i eelised SOAPi ees:

• Paindlikkus ja lihtsus: REST on lihtsam ja paindlikum kasutada.
• Vähem lisatarkvara: REST töötab hästi HTTP ja JSONiga, mida enamik keeli toetab.
• Madalam õppimiskõver: REST API toimib sarnaselt veebiserveriga, edastades JSON-i HTML-i asemel.
• Parem jõudlus ja võrgukasutus: REST kasutab kompaktsemat JSON-i, samas kui SOAP kasutab XML-i, mis on mahukam.
• Lähedus teistele veebitehnoloogiatele: REST kasutab HTTP meetodeid ja URL-e loomulikul viisil.

Peamine erinevus on keerukus: REST on lihtsam ja kergemini rakendatav.

URI RESTis ja SOAPis erinevused

RESTful API-s tehakse serveri andmebaasis olevad andmed kättesaadavaks ressurssidena, kus igale ressursile on määratud oma URI (uniform resource identifier). Need URI-d eristavad eri tüüpi andmeressursse, näiteks /invoices, /accounts, /payments, /orders. URI-d on nimisõnad ja mitmuses, näiteks /cars, mitte /car ega /getCar. Sisselogimiseks kasutatakse kollektsiooni /sessions.

SOAPis sõltub URI kasutatavast bindingust. SOAP HTTP Binding võimaldab siduda SOAP-i meetodeid HTTP meetoditega, määrates URI, näiteks /accounting-web-service.

Kuidas erineb käsu (ehk tegevuse, mida soovitakse teha) edastamine

SOAPis on andmeedastus HTTP kaudu kahte tüüpi:

• SOAP Request-Response: Klient saadab alati POST päringu, kus XML dokument sisaldab vajalikku funktsiooni ja argumente.
• SOAP Response: Sarnaneb REST-ile, kus GET päringud saadetakse andmete saamiseks ja need edastatakse URL-ina (/func1?arg1=foo&arg2=bar), kuid seda kasutatakse harva.

REST-is kasutatakse HTTP meetodeid vastavalt päringu tüübile:

• GET: Andmete hankimine kollektsioonist või üksikust elemendist.
• PUT: Elemendi andmete täielik uuendamine.
• POST: Uute andmete saatmine või olemasoleva elemendi muutmine.
• PATCH: Olemasoleva elemendi osalised muutmised.
• DELETE: Elemendi või andmete kustutamine kollektsioonist.

JSON struktuur

JSON on lihtne andmevahetusformaat, mis kasutab JavaScripti süntaksit, kuid ei piirdu ainult JavaScriptiga. See tekstivorming esitab andmeid objekti- ja massiivstruktuurides, olles toetatud kõigis kaasaegsetes programmeerimiskeeltes. JSON on eriti populaarne REST API-de puhul.

JSON-objekti struktuur on järgmine:

• Objektid on kujul {}, kus andmed on komadega eraldatud võtmeäärtuse paaridena. Võtmed on jutumärkides.
• Massiivid on kujul [], sisaldades elemente, mis võivad olla stringid, objektid, massiivid või muud JSON-i toetatud andmed.
• Stringid on alati jutumärkides.

JSON võimaldab piiramatu pesastamise, võimaldades kirjeldada erinevaid andmetüüpe, sealhulgas keerulisi struktuure.

JSON andmetüübid

• 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.

Andmete puhverdamine

Andmete puhverdamine (data caching) salvestab andmeid ajutisse vahemällu, et neid saaks kiiremini kätte saada ja vältida igakordset allalaadimist.

Andmete dubleerimine (data replication) loob andmete koopiaid ja hoiab neid erinevates kohtades, et:

• Parandada andmete kättesaadavust
• Suurendada juurdepääsu kiirus
• Parandada serveri jõudlust
• Tagada andmete taastamine

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.

Küpsised

Kui klient saadab HTTP päringu, luuakse ajutine TCP sessioon, kuid pärast vastuse saamist katkestatakse ühendus. Kui klient teeb uue päringu, peab ta looma uue TCP ühenduse, mistõttu server ei pruugi teada, kas tegemist on sama kliendiga.

Küpsised (cookies) on väikesed nimi=väärtus paarid, mida server saadab kliendile, et säilitada teavet ja tuvastada klient järgmistes päringutes.

localStorage töötamine

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

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.