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

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.

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

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. 

REST on väga arendajasõbralik, sest selle kasutamine on palju lihtsam kui SOAP. Lisaks on REST vähem sõnarikkam ja kahe lõpp-punkti vahelisel suhtlemisel saadetakse vähem andmemahtu. REST lahendas SOAPi keerukuse probleemid ja nüüd on praktiliselt kõik avalikud API-d REST API-d.

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

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.

SOAP või REST?

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:

Siiski põhiline, mis eristab SOAPi RESTist on keerukus: REST on kergesti mõistetav ja rakendatav.

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)

Erinevus 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

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

Kui SOAPis kasutada andmeedastusviisiks HTTP protokolli, on valida kahe mustri vahel: SOAP Request-Response message exchange pattern ja SOAP Response message exchange pattern. Esimese puhul saadab klient mistahes päringu alati POST päringuna ja andmed nagu mis funktsioon serveris käivitada ning milliste argumentidega, on kodeeritud POST päringu kehana saadetavas XML dokumendis; teine töötab rohkem nagu REST: need päringud, mis andmeid küsivad ja neid ei muuda, saadetakse GET päringuna ja vajalikud andmed edastatakse päringu rajana (/func1?arg1=foo&arg2=bar), kuid seda režiimi rakendatakse praktikas väga harva. 

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

Näiteks arve kustutamine tuleb kindlasti teha DELETE päringuga (nt DELETE /invoices/42), mitte POST päringuga (nt POST /invoices?id=42&action=delete või midagi sellist), sest DELETE on otseselt kustutamiseks, POST aga üldiselt andmete serverisse saatmine töötluseks ja alati tuleks eelistada seda meetodit. Kui on kahtlus, millist HTTP meetodit peaks mingil momendil kasutama, tuleks pöörduda HTTP spetsifikatsiooni poole ja lugeda meetodite selgitusi. HTTP spetsifikatsioon kannab tähistust RFC 7231 ning meetodite kirjeldus on toodud selle spetsifikatsiooni sektsioonis 4.3. (otselink: https://datatracker.ietf.org/doc/html/rfc7231#section-4.3)

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. 

REST server võtab päringusõnumi vastu ja käivitab seejärel koodi, mis kontrollib vajadusel päisest juurdepääsuõigust, loeb siis andmebaasist soovitud andmed (või hoopis paneb nad sinna kui oli POST päring) ja seejärel vormindab andmetest vastussõnumi:

Sõnumi ülemine osa, staatus-rida, sisaldab staatuskoodi, mis ütleb kliendile, mis tema päringuga juhtus. Koodid 200-299 tähendavad, et kõik läks hästi. 400-499 koodid tähendavad, et sinu päringuga oli midagi valesti ja 500-599 tähendavad, et serveris oli mingi viga. Üks väga kasulik veebisait, kus on kõik staatuskoodid koos selgitustega ära toodud, on https://httpstatuses.com. 

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.