AKTAR

1. Veebiteenus vs API

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.

Kõik veebiteenused on API-d, aga kõik API-d ei ole veebiteenused. Näiteks on olemas Windows API, mida kõik Windowsi töölauarakendused kasutavad ja mis võimaldab neil kasutada operatsioonisüsteemi sisse ehitatud funktsionaalsust, näiteks paluda operatsioonisüsteemil kuvada kasutajale mingi teade. Ja riistvaraga suhtlemiseks on eraldi API-d (OpenGL, Metal, Direct3D).

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. 

3. REST

REST-i (Representational State Transfer) on tavaliselt nimetatud pigem veebiteenuste arhitektuuristiiliks kui protokolliks või standardiks. See tuleneb sellest, et REST ei määratle sõnumi sisu, vaid ainult teatud tingimusi, millele eeskujulik veebiteenus, mida on lihtne ja mugav kasutada, peaks vastama. Ka REST võimaldab suhtlust kahe tarkvaraprogrammi vahel: üks programm saab teiselt programmilt ressursse taotleda ja nendega manipuleerida. REST on üles ehitatud HTTP-protokollile, kasutades URL-ile sarnaseid viiteid ressurssidele, mida nimetatakse URI-deks (Uniform Resource Identifier) ja HTTP verbe nagu GET, POST, PUT ja DELETE, mis näitavad, millist tegevust klient ressursiga soovib teha. REST kasutab andmete edastamiseks kodeerimisformaate nagu XML, HTML või JSON. Kõige eelistatum on JSON, kuna see on kõige ühilduvam ja lihtsamini kasutatav. 

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?

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)
• Siiski põhiline, mis eristab SOAPi RESTist on keerukus: REST on kergesti mõistetav ja rakendatav.

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

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

REST-i puhul edastatakse aga käsk kasutades HTTP meetodit, mis vastab kõige rohkem päringu olemusele:

REST-is teeb klient HTTP päringuid vastava kollektsiooni URI pihta. URI nimetatakse vahel ka lõpp-punktiks (endpoint). Päring on tavaline HTTP päring: algab nn päringu-reaga (Request-Line), mis sisaldab HTTP meetodit (kirjeldab ressursiga tehtavat toimingut) ja URI. 

Näiteks GET meetod tähendab, et soovid lihtsalt andmeid lugeda, POST tähendab, et soovid luua uue ressursi, PATCH on uuenduste jaoks ja DELETE on andmete eemaldamiseks. Peale nende on veel mõned muud meetodid lisaks eelnevatele. 

Pärast esimest rida on päised, mis sisaldavad metaandmeid taotluse kohta. Näiteks päisega Accept saab öelda serverile, et tahad andmeid mingis konkreetses formaadis saada ja päis Authorization sisaldab andmeid, mis tõendavad serverile, et sul on õigus seda päringut teha. Päistele järgneb keha ehk päringu sisu. 

Pärast staatuskoodi on vastuse päised (response headers), mis sisaldavad teavet serveri kohta. Sellele järgneb vastuse keha (response body), mis sisaldab soovitud andmeid (payload) ja on API-de puhul tavaliselt vormindatud JSONis või XML formaadis. REST arhitektuuri oluline osa on see, et see on olekuta (stateless), mis tähendab, et kaks osapoolt ei pea salvestama üksteise kohta mingit teavet ja iga päringu-vastuse tsükkel on sõltumatu kogu muust suhtlusest. Pole nii, et kõigepealt saadad ühe päringu, mis loob serveris mingi oleku ja alles siis saad edukalt teise saata (niiviisi käitub näiteks SMTP protokoll, millega e-maile saadetakse). See tagab, et veebirakendused oleksid korrektsed ja töökindlad.