Tietorajapinta (REST)
Tietorajapinta on REST/HTTP-rajapinta. Tietorajapinta mahdollistaa datahubissa olevien tietojen haun esimerkiksi suoraan markkinaosapuolen loppuasiakkaillensa tarjoamaan online-palveluun. Tietorajapinnan kautta ei voi ilmoittaa tietoja datahubiin. Markkinaosapuolet voivat itse päättää haluavatko tätä rajapintaa hyödyntää omassa toiminnassaan. Osapuolten oikeudet tietoihin otetaan huomioon samojen sääntöjen mukaisesti sekä tietorajapinnan että tapahtumarajapinnan osalta. Osapuoli voi hakea vain tietoja, joihin osapuolella on oikeus sopimuksen perusteella tai asiakkaan valtuuttamana.
Mikäli osapuolilla on tarve hakea isompaa tietomäärää kerralla, esimerkiksi verratakseen datahubissa olevaa tietoa oman järjestelmänsä tietoihin, tulee tähän tarkoitukseen käyttää datahubin tarjoamia kontrolliraportteja. Näitä raportteja voidaan ajaa ajastetusti esim. yöaikaan häiritsemättä muuta päivittäistä toimintaa.
Tietorajapinta tarjoaa seuraavanlaiset tietohaut:
Käyttöpaikkatietojen haku
Käyttöpaikan sopimustietojen haku
Käyttöpaikan mittaustietojen haku
Käyttöpaikan valtuutustietojen haku
Asiakkaan asiakastietojen haku
Osapuolitietojen haku: Osapuolitietojen osalta voidaan hakea kaikkien osapuolten tiedot kerralla.
Tietorajapinnan käytössä huomioidaan osapuolten oikeudet tietoon samoilla säännöillä kuin sanomarajapinnassa. Osapuoli saa tämän rajapinnan kautta käyttöönsä ainoastaan ne tiedot mihin tällä on oikeus joko sopimuksen tai valtuutuksen kautta. Tietosuojan varmistamiseksi hakuun tulee syöttää aina myös asiakkaan tunnus, jonka kanssa sopimus on tehty. Yhden asiakkaan tunnus riittää myös siinä tapauksessa, jos sopimuksella on useampi asiakas.
Datahubin tietorajapinnan käyttö on kuvattu osiossa DH-1000 Tietojen noutaminen tietorajapinnan kautta.
Suositukset rajapinnan käytöstä
Tietorajapintaa ei ole tarkoitettu massahakujen tekemiseen. Tietorajapinnalla tiedot haetaan aina yksilöiden tietokokonaisuus kerrallaan. Tämä tarkoittaa sitä, että haussa ilmoitetaan esim. haettavan käyttöpaikan tietojen käyttöpaikkatunnus. Mikäli haluttaisiin hakea useamman käyttöpaikan tietoja yhdellä kertaa, on tapahtumarajapinta tehokkaampi tapa tietojen hakuun.
Tapahtumarajapinnan etu on myös siinä, että tietoihin tapahtuvista muutoksista datahub välittää automaattisesti tiedon siihen oikeutetuille osapuolille. Tietorajapinnan käyttäjän on erikseen osattava hakea muuttunut tieto.
Rajaukset rajapinnan käyttöön
Tietorajapintaa hyödyntäen ei voi ilmoittaa tietoja datahubiin.
Tietorajapinnan kautta ei löydy käyttöpaikkatunnuksen selvitystapahtuman kaltaista toiminnallisuutta. Haettava tieto on aina yksilöitävä, eli haussa on annettava aina esim. haettavan käyttöpaikan käyttöpaikkatunnus tai asiakkaan asiakastunnus.
Tietorajapinta ei tue toimeksiantoja osapuolten välillä.
Palveluntarjoajan roolissa toimivalla osapuolella tulee aina olla asiakkaan antama valtuutus, ennen kuin osapuoli voi hakea tietoja. Valtuutus on aina asiakas- ja käyttöpaikkakohtainen.
Esimerkkejä rajapinnan käytöstä
Tietorajapintaa voidaan käyttää esimerkiksi silloin, kun ulkopuolinen rekisteröity osapuoli (kolmas osapuoli tai muu markkinaosapuoli) kehittää ja luo uusia palveluita. Kolmannen osapuolen palvelu voi olla esimerkiksi mobiilisovellus, jonka avulla loppukäyttäjä voi nähdä kaikkien käyttöpaikkojen tiedot riippumatta siitä, millä verkkoalueella käyttöpaikat sijaitsevat. Tällainen edellyttää aina asiakkaan ilmoittamaa valtuutusta datahubiin. Asiakastietoja hakiessa tulee aina ilmoittaa haettavan asiakkaan asiakastunnus. Datahub tarkistaa, onko hakijalla oikeus asiakkaan tietoihin ja palauttaa tiedot vain, jos oikeus on voimassa.
Esimerkkejä hauista:
Haetaan asiakastiedot, GetCustomerData (DH-1005)
Tiedettävä asiakastunnus (HeTu, Y-tunnus)
Tietojen saamiseksi on oltava oikeus tietoihin (sopimus tai valtuutus)
Palauttaa käyttöpaikat, joihin asiakkaalla on sopimukset