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.

Joonis 1: API kasutamine on nagu kaks rakendust vestleksid omavahel sõnumirakenduses.

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.

2. SOAP

SOAP (lühend fraasist Simple Object Access Protocol) on natuke vanem veebiteenuste loomise viis, mis leidis varem laialdast kasutust. SOAP on väga ulatuslik, kuid keeruline standardite kogum. Microsofti meeskond kavandas selle äärmiselt paindlikuks, et võimaldada suhtlust nii privaatvõrkudes, internetis kui ka isegi elektronposti kaudu.

UDDI ja WSDL

SOAP-i esialgses spetsifikatsioonis olid UDDI (Universal Description, Discovery and Integration) — teenuste leidmise standard — ja WSDL (Web Services Description Language) — teenuste dokumenteerimise standard. Kuid UDDI ei saavutanud suurt populaarsust ja seda enam ei arendata.

SOAP sõnumi struktuur

SOAP sõnum koosneb kohustuslikest osadest:

• ENVELOPE — kogu sõnumi ümbrik.
• HEADER — valikuline päis, mis sisaldab lisateavet.
• BODY — sõnumi põhisisu ehk päring või vastus.
• FAULT — veateateid käsitlev osa.

Kommunikatsioon toimub tavaliselt HTTP POST päringutena, kus XML vormingus sõnum on päringu kehas.

3. REST

REST (Representational State Transfer) on arhitektuuristiil, mis määratleb teatud reeglid ja piirangud veebiteenuste kujundamiseks. REST kasutab HTTP meetodeid nagu GET, POST, PUT, DELETE, PATCH ning URI-sid ressursside identifitseerimiseks.

REST ei ole ametlik standard, vaid pigem parimate praktikate kogum, mille eesmärk on lihtsustada ja kiirendada API-de arendamist.

REST kasutab tavaliselt JSON formaati andmete edastamiseks, mis on kerge, kiire ja laialt toetatud.

REST teenused on olekuta (stateless), mis tähendab, et iga päring on sõltumatu ja ei sõltu varasematest päringutest.

4. RESTful API

RESTful API tähendab, et teenus järgib REST-i põhimõtteid:

• Ressursid on URL-idena kättesaadavad (nt /users, /orders).
• Kasutatakse HTTP meetodeid ressursi manipuleerimiseks.
• Sõnumid on minimaalsed ja hästi struktureeritud.
• Iga päring sisaldab kogu vajaliku info.

5. Valik SOAPi ja RESTi vahel

SOAP:

• Transpordist sõltumatu (kasutab XML-i sõnumites).
• Sobib keerukatele, hajutatud ärikeskkondadele.
• On tugevasti standardiseeritud.
• Sisaldab sisseehitatud veahaldust ja turvastandardeid.
• Sobib, kui vaja keerulist äriloogikat ja kindlaid protokolle.

REST:

• Lihtne ja kiire kasutada.
• Vähem ressursimahukas (kasutab JSON).
• Hea valik avalike API-de jaoks.
• Vähem keeruline.
• Ei nõua täiendavat tarkvara HTTP kaudu suhtlemiseks.

6. URI ja päringud SOAPis ja RESTis

REST API puhul on iga ressurss omistatud URI-le, mis on tavaliselt nimisõna mitmuses (nt /invoices, /users).

SOAPis sõltub URI struktuur bind’ist (SOAP HTTP Binding) ja sõnum ise on XML dokumendis POST päringu kehas.

7. Päringu ja vastuse mustrid

SOAP kasutab tavaliselt POST päringuid, kus kogu info on XML sees.

REST kasutab HTTP meetodeid vastavalt toimingule:

8. HTTP päringu ja vastuse anatoomia RESTis

• Päringu esimene rida koosneb HTTP meetodist ja URI-st.
• Päised (headers) annavad lisainfot, nt Accept või Authorization.
• Päringu keha sisaldab andmeid, nt POST päringul JSON objekti.
• Vastuse staatuskood näitab tulemust (200 = OK, 404 = Not Found jne).
• Vastuse keha sisaldab tavaliselt JSON või XML vormingus andmeid.

9. Praktilised näited SOAP ja REST päringutest

SOAP näide: ilmastikuinfo päring

SOAP päring:

POST /WeatherService HTTP/1.1
Host: www.example.com
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://www.example.com/GetTemperature"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetTemperature xmlns="http://www.example.com/weather">
      <City>Москва</City>
    </GetTemperature>
  </soap:Body>
</soap:Envelope>

SOAP vastus:

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetTemperatureResponse xmlns="http://www.example.com/weather">
      <Temperature>5</Temperature>
    </GetTemperatureResponse>
  </soap:Body>
</soap:Envelope>

REST näide: ilmastikuinfo päring

REST päring:

nginx:

GET https://api.example.com/weather?city=Москва

REST vastus:

json:

{
  "city": "Москва",
  "temperature": 5,
  "unit": "C"
}

REST näide: uue kasutaja loomine

Päring:

POST https://api.example.com/users
Content-Type: application/json

{
  "name": "Иван Иванов",
  "email": "ivan@example.com"
}

Vastus:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 123,
  "name": "Иван Иванов",
  "email": "ivan@example.com"
}

10. Kokkuvõte

• SOAP on keerukam, aga stabiilsem ja standardiseeritum, sobib suurtesse ärisüsteemidesse.
• REST on lihtsam, kiire ja paindlik, sobib enamasti avalike API-de ja veebi jaoks.
• Valik sõltub projekti nõuetest, keelest ja meeskonna oskustest.