Help

REST

Tämä kuvaus REST-rajapinnasta on suunnattu lähinnä ohjelmistokehittäjille. Mikäli aihepiiri ei ole entuudestaan tuttu, kannattaa siihen tutustua esim. wikipediasta.

Johdanto

REST-rajapinnalla tarkoitetaan ohjelmallista rajapintaa, jolla tietoja saadaan tuotua ja vietyä sisään ValueFrameen yksinkertaisessa JSON-muodossa. REST ei ole varsinainen standardi vaan yleinen tapa tietojärjestelmien tiedonvaihtoon. Tästä syystä eri ohjelmistojen REST-toteutukset voivat hieman poiketa toisistaan. 

Useissa tapauksissa ValueFramen tietoihin päästään suoraan RESTin kautta käsiksi ilman erillistä ohjelmointia (ns. taulupohjainen REST), mutta monimutkaisemmissa tilanteissa ja erityisesti jos tietoja täytyy muokata ohjelmointityö voi olla tarpeen. Tällöin yksittäisten tietokantataulujen sijaan rajapinta voidaan ohjelmoida (ns. luokkapohjainen REST) taulumäärityksen sijaan.

ValueFramen REST-rajapinnasta löytyy valmiita malleja molempiin edellä mainittuihin tilanteisiin. Kutsuvan ohjelman näkökulmasta käyttö on molemmissa tilanteissa samanlaista:

https://psa.valueframe.com/rest/v2/{REST_resurssi}/

ValueFramen REST-rajapinta määritellään aina asiakaskohtaisesti. Tämä mahdollistaa käytännössä resurssien avaamisen ja muokkaamisen käyttöön täysin tarpeen mukaan (esim. vain lukemista varten). Rajapinnasta voidaan näin ollen toteuttaa mahdollisimman yksinkertainen ja turvallinen, mutta kuitenkin tarpeet täyttävä. Rajapinta voidaan avata helposti lukutarkoituksiin mm. seuraaviin ValueFramen objekteihin:

  • Asiakkaat
  • Kontaktit
  • Projektit
  • Osaprojektit
  • Tuntikirjaukset
  • Resursoinnit
  • Matkalaskut
  • Kohteet
  • Hankkeet
  • Kalenteritapahtumat
  • Henkilöt (=työntekijät)
  • Tehtävät
  • Ostot / Myynnit
  • Tarjoukset
  • Laskut

Vaihtoehdot REST-rajapinnan käyttämiselle

RESTin käyttö edellyttää lähes aina ohjelmointityötä ValueFramen REST-rajapintaa hyödyntävän ohjelmiston puolelle. Tästä syystä voi olla hyvä miettiä, onko REST välttämättä paras mahdollinen integraatio-tapa. Muita vaihtoehtoja ovat mm.

  1. ValueFramesta saa tietoa ulospäin myös tietovarastopalvelun avulla. Tietovarastopalvelussa tiedonsiirto on aina yhdensuuntaista — tietokannasta ulospäin. Tästä johtuen tietovarastopalvelu sopiikin tilanteisiin, joissa tarvitaan suora, reaaliaikainen pääsy ValueFramen tietokantatason dataan, mutta ei välttämättä mahdollisuutta tallentaa tietoa takaisin ValueFrameen päin. Tietovarastopalvelun käyttäminen yhdessä REST-rajapinnan kanssa on mahdollista.
  2. ValueFramen listausten tai raporttien tallentaminen esim. Excel-muodossa suoraan ValueFramen käyttöliittymästä.
  3. Näkymien tallentaminen XLS-muotoon. 
  4. Räätälöity rajapinta tietojen export/import -tarpeisiin. Joissain ohjelmistoissa tiedonvaihto saattaa olla rajoitettu esim. vain SOAP-rajapintaan, jolloin REST-rajapintaa ei voida suoraan hyödyntää. 

Autentikointi

Jokainen REST-kutsu täytyy autentikoida. Autentikointi tekee seuraavat tarkistukset:

  1. Tarkistetaan vaaditut header-määreet. Jokainen näistä on oltava olemassa ja arvot eivät saa olla tyhjiä
    • X-VF-REST-USER
    • X-VF-REST-TIMESTAMP
    • X-VF-REST-HASH
  2. Yritetään luoda tietokantayhteys
    • X-VF-REST-USER -tiedon pohjalta esim. devel.valueframe.com
  3. Tarkistetaan kutsun aikaleima (X-VF-REST-TIMESTAMP)
    • Lähetettävä tieto on lähettäjän päässä generoitu UNIX-timestamp
    • Aikaleima tulee olla generoitu kymmenen (10) minuutin sisällä siitä kun REST-kutsu lähetetään palvelimmelle
  4. Tarkistetaan kutsun tarkistesumma (X-VF-REST-HASH)
    • Tämä on clientin päässä generoitu md5 hash seuraavista arvoista: aikaleima + resurssin osoite + siirtoavain ( esim. PHP md5(time(‘U’) .”/tehtavan_kommentti/” . “Siirtoavain”) )
    • Palvelin päässä generoidaan sama hash käyttäen X-VF-REST-USER -määrittämän tietokannasta löytyvää siirtoavainta, clientin lähettämää X-VF-REST-TIMESTAMP -arvoa sekä REST resurssin osoitetta.
Header Oletusarvo Mahdolliset arvot Pakollinen Selitys
X-VF-REST-USER   VF-sisäänkirjautusosoite X Tämä määrittelee ValueFrame asiakkuuden esim. asiakas.valueframe.com.
X-VF-REST-TIMESTAMP 0   X REST-pyynnön kutsun UNIX-aikaleima.
X-VF-REST-HASH     X

REST-pyynnön HASH. MD5 tarkistesumma md5({X-VF-REST-TIMESTAMP} .’/’. {REST Resurssi} .’/’. {SIIRTOAVAIN})

MD5 tarkistussumma tulee lähettää pienillä kirjaimilla. Siirtoavain on määritellään ValueFramen käyttöliittymässä yhtiön tietoihin ylläpitäjän oikeuksilla.

X-VF-REST-TYPE JSON JSON / XML / CSV / TSV  

Tämän avulla client voi valita missä formaatissa se haluaa REST rajapinnan käsittelevän tietoja. Vaikuttaa sekä output tietoihin että input datan käsittelyyn.

CSV/TSV -muodot ovat käytettävissä vain GET-metodilla.

X-VF-REST-ZIP 0 0 / 1   Tämän header tiedon avulla Client voi pyytää GET-kutsun tiedot pakattuna. Tässä tapauksessa output data on seuraavan muotoinen

JSON: {“data”: “…”} XML: <data>…</data>.

Varsinainen data sisältö on base64-enkoodattu merkkijono ZIP-datasta.

Virheiden käsittely

Rajapinnan antamat statuskoodit.

VARATUT SANAT

REST-rajapinnoissa on niin kutsuttuja varattuja sanoja, joilla voidaan esimerkiksi kysyä palautettavan tulosjoukon kokoa, määrittää mitkä tietueet ja kuinka monta tietuetta kysely palauttaa ja niin edelleen. Varatut sanat ovat:

  • count
  • limit
  • offset
  • schema

Count

Count palauttaa resurssien tietueitten kokonaismäärän.

Esimerkki

Kutsu: https://psa.valueframe.com/rest/v2/account?count

Vastaus: “count”:12

LIMIT&OFFSET

Limit– ja offset-määreet toimivat yhdessä siten, että limit rajoittaa palautettavan joukon koon (tietueiden määrä) ja offset taas määrittää nk. offsetin datajoukon alusta lähtien, mistä palautettava joukko alkaa.

Esimerkiksi

https://psa.valueframe.com/rest/v2/account?limit=5&offset=0

palauttaa 5 tietuetta ensimmäisestä tietueesta lähtien.

https://psa.valueframe.com/rest/v2/account?limit=5&offset=1

palauttaa 5 tietuetta toisesta tietueesta lähtien.

Schema

Schema palauttaa kyseessä olevan REST-resurssin skeeman (rakenteen).

Esimerkiksi

https://psa.valueframe.com/rest/v2/account/?schema

palauttaa asiakas-rajapinnan rakenteen.

REST-rajapinnan käyttö

TAULUPOHJAINEN REST-rajapinta

Yksinkertaisissa tilanteissa REST-rajapinta voidaan toteuttaa pelkällä määrittelyllä ilman varsinaista ohjelmointia. Tällöin tyypillisesti yksittäinen REST-resurssi käsittelee vain yhtä tietokantataulua. Myös useamman tietokantataulun hakeminen kerralla on mahdollista, kun taustalle luodaan sopiva tietokantanäkymä RESTiä varten.

Kutsuesimerkkejä GET-metodista

Edellä listattu ensimmäinen esimerkki voisivat palauttaa esim. seuraavan muotoisen JSON-muotoisen tuloksen:

{  
  "AccountCollection": {    
    "Account": [
      {
        "AccountId": 1,
        "AccountName": "K-Mania Oy",
        "AccountCity": "HELSINKI"
      },
      {
        "AccountId": 2,
        "AccountName": "Prodigal Oy",
        "AccountCity": "JYVÄSKYLÄ"
      }
    ]
  }
}

Tietojen tuominen POST-metodilla

Rajapinnan määrittelyssä tietojen oikeellisuuteen voi taulupohjaisessa REST-rajapinnassa tehdä seuraavat tarkistukset:

  • Tietyt kentät voi määritellä pakolliseksi.
  • Kenttä voidaan validoida numeerikseksi tai aakkosnumeeriseksi.
  • Kenttä voidaan määrittellä sallimaan NULLit.
  • Kenttä voidaan tarkistaa jonkun toisen taulun tietosisällön mukaan, esim. työntekijän ID täytyy löytyä taulusta HENKILO.ID.
  • Kenttä voidaan validoida olevan joku muu sallituista arvoista, esim. 1, 2 tai 3.
  • Kentälle voidaan asettaa oletusarvo.

Edellä listattuihin määrittelyihin otetaan kantaa kenttätasolla rajapintaa määriteltäessä. Mikäli määrittelyillä ei päästä riittävän tarkkoihin tarkistuksiin tai taustalle tarvitaan ValueFramen puolen ohjelmointilogiikkaa, tulee käyttää luokkapohjaista REST-rajapintaa.

LUOKKAPOHJAINEN REST-rajapinta

Ohjelmallisessa REST-toteutuksessa rajapinta voi toteuttaa GET / POST / PUT / DELETE -metodit tarpeen mukaan.

emaileri-integraatio

emaileri-integraatiossa emaileri-ohjelmisto hakee postituslistat ValueFramen luokituksista ja päivittää näiden perusteella ValueFrameen tiedon sähköpostin avanneista kontakteista ja markkinointikielloista.

Kutsuesimerkkejä:

emaileri-rajapinnan tarkempi dokumentaatio on käytettävissä integraatiokumppaneille.

Tuntikirjaus-integraatio

Rajapinnan avulla on mahdollista luoda tuntikirjauksia ulkopuolisesta järjestelmästä ValueFrameen.

Kutsuesimerkkejä:

Tuntikirjaus-rajapinnan tarkempi dokumentaatio on käytettävissä integraatiokumppaneille.