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


HeaderOletusarvoMahdolliset arvotPakollinenSelitys
X-VF-REST-USER VF-sisäänkirjautusosoiteXTämä määrittelee ValueFrame asiakkuuden esim. asiakas.valueframe.com.
X-VF-REST-TIMESTAMP0 XREST-pyynnön kutsun UNIX-aikaleima.
X-VF-REST-HASH  X

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


Huom! 18.9.2024 kaikilla asiakkailla tarkistesumma lasketaan algoritmilla sha512 eli SHA512 tarkistesumma sha512({X-VF-REST-TIMESTAMP} .’/’. {REST Resurssi} .’/’. {SIIRTOAVAIN}) 


MD5/SHA512 tarkistussumma tulee lähettää pienillä kirjaimilla. Siirtoavain määritetään ValueFramen toimesta.


X-VF-REST-TYPEJSONJSON / 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-ZIP00 / 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.



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

Send feedback
Pahoittelut, että emme voineet auttaa. Anna palautetta, jotta voimme parantaa tätä artikkelia.