REST-rajapinnan käyttö

• REST-rajapinta
• Vaihtoehdot REST-rajapinnan käyttämiselle
• Autentikointi
• Varatut sanat
• REST-rajapinnan käyttö

REST-rajapinta

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

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://rest.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:

• 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
  
  
• Yritetään luoda tietokantayhteys
  • X-VF-REST-USER -tiedon pohjalta esim. devel.valueframe.com
  
  
• 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
  
  
• 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.
  • Huom! 18.9.2024 kaikilla asiakkailla tarkistesumma lasketaan algoritmilla sha512 eli: ( esim. PHP sha512(time(‘U’) ."/tehtavan_kommentti/" . "Siirtoavain") ) 
  
  

Käytettävälle siirtoavaimelle ei ole automaattista rotaatiota. Mikäli haluatte vaihtaa siirtoavaimen, ottakaa yhteyttä ValueFarmen tukeen, tuki hoitaa avaimen vaihtamiseen liittyvät toimenpiteet. 

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://rest.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://rest.valueframe.com/rest/v2/Account?limit=5&offset=0

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

https://rest.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://rest.valueframe.com/rest/v2/Account?schema 

palauttaa asiakasrajapinnan 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

GET https://rest.valueframe.com/rest/v2/Account/ , palauttaa kaikki asiakkaat
GET https://rest.valueframe.com/rest/v2/Account/8, palauttaa asiakkaan ID 8
GET https://rest.valueframe.com/rest/v2/Account?AccountName=Fors palauttaa asiakkaat, jonka nimessä esiintyy merkkijono "Fors". Eli asiakkaita voidaan hakea nimellä, jos nimi on  kirjoitettu täsmälleen samalla. 

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.

Sähköposti-integraatio

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

Kutsuesimerkkejä:

GET https://asiakas.valueframe.com/rest/v2/Emaileri/Kontakti/8, palauttaa kontaktin ID 8
GET https://asiakas.valueframe.com/rest/v2/Emaileri/17/Kontakti/8, palauttaa kontaktin ID 8 luokasta 17

Tuntikirjaus-integraatio

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

Kutsuesimerkkejä:

POST https://rest.valueframe.com/rest/v2/TimeSheet/, luo uuden tuntikirjauksen
GET https://rest.valueframe.com/rest/v2/TimeSheet/123, hakee tuntikirjaus ID 123

Tuntikirjaus-rajapinnan tarkempi dokumentaatio löytyy Tuntikirjausrajapinta-artikkelista..

Oliko tästä vastauksesta apua? Kyllä Ei