Ohjelmallinen rajapinta (API)

Suomen tutkimusinfrastruktuurit -palvelun sisältämään dataan on tarjolla pääsy tällä sivulla kuvatun rajapinnan kautta.

 

Miksi käyttää rajapintaa?

Tutkimusinfrastruktuurien tietopankin tietojen käytöstä ohjelmallisen rajapinnan kautta on seuraavat hyödyt:

  • Keskitetty, helposti ylläpidettävä tietolähde infrastruktuureista
  • Tiedon varmuus ja yhteismitallisuus: kuvailutiedot infrastruktuurien itsensä antamia sekä tutkijoiden ja rahoittajien kanssa yhteisesti suunnitellussa muodossa
  • Mahdollistaa tiedon rikastamisen eri lähteitä yhdistämällä
  • Toistuvan päällekkäisen tiedonsyötön vähentäminen automatisoimalla

 

Tekninen kuvaus ja käyttöohjeet

Alla yksinkertaistettu kuvaus skeemasta, jossa esillä neljä keskeistä kokonaisuutta datassa: Infrastruktuurit, Palvelut, Organisaatiot ja Yhteystiedot.

Tarkempi skeemakuvaus löytyy Yhteentoimivuuden kuvaukset -palvelusta: http://iow.csc.fi/model/tipa/

Jokaiseen neljään kokonaisuuteen liittyy metodeja, joilla tietopankin sisältämiä tietoja voidaan hakea. Rajapinta on rakennettu Liferayn sisältämällä (JSONWS) -työkalulla ja se tarjoaa vastaukset JSON-muotoisena. Kyselyitä voidaan tehdä esimerkiksi curl-ohjelmalla, suoralla URL-viittauksella ja Liferayn käyttöliittymän avulla.

Rajapinta löytyy osoitteesta: http://avaa.tdata.fi/api/jsonws?contextPath=/tupa-portlet

Rajapinnan toiminnallisuuksien kuvailut löytyvät kyselyllä: curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Helper/get-capabilities

JavaDocin kaltainen dokumentaatio löytyy osoitteesta: http://avaa.tdata.fi/adata/tupa/

Kysymyksiä ja kommentteja voi lähettää osoitteeseen avaa (at) csc.fi

 

Esimerkkejä

Alla muutamia yksinkertaisia esimerkkejä rajapintakyselyistä. 

Huomio: Erotusmerkkeinä listamuotoisille parametreille ovat joko pilkut (",") tai puolipisteet (";"). Merkkijonot tulee ympäröidä lainausmerkeillä  (" "" " tai " '' "). Alla olevissa esimerkkivastauksissa kolme pistettä ("…") merkitsevät esimerkin luettavuuden vuoksi pois jätettyä kohtaa.

Kohde: Organisaatio (TpOrganisation)
Metodi:  get-organisations-by-organisations-ids (getOrganisationsByOrganisationsIds)
Selitys: palauttaa listan Organisaatioita annettujen tunnisteiden perusteella
UI: http://avaa.tdata.fi/api/jsonws?contextPath=/tupa-portlet&signature=%2Ftupa-portlet%2FOrganisations%2Fget-organisations-by-organisations-ids-1-organisationsIds
Parametrit: organisaatioiden tunnisteet
Parametrityyppi: vaihtelevakokoinen lista positiivisia kokonaislukuja

URL-kyselyesimerkki organisaatioille, joiden tunnukset ovat 1 (yksi) ja 3 (kolme):

  1. curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Organisations/get-organisations-by-organisations-ids/organisations-ids/1%2C3
  2. curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Organisations/get-organisations-by-organisations-ids/organisations-ids/1%3B3
  3. curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Organisations/get-organisations-by-organisations-ids/organisations-ids/%221%22%2C%223%22
  4. curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Organisations/get-organisations-by-organisations-ids/organisations-ids/'1'%2C'3'

Vastaus:
[
  {
    "contactsIds": [26, 27],
    "country": "FI",
    "id": 1,
    "infrastructuresIds": [18],
    "isni": "0000 0001 2198 1512",
    "motherOrganisationsIds": 0,
    "name_EN": "University of Turku",
    "name_FI": "Turun yliopisto",
    "servicesIds": [119, ... , 125]
  },
  {
    "contactsIds": [1, ... , 40],
    "country": "GB",
    "id": 3,
    "infrastructuresIds": [1, 17, 21],
    "isni": "",
    "motherOrganisationsIds": 0,
    "name_EN": "United Kingdom",
    "name_FI": "Yhdistynyt kuningaskunta",
    "servicesIds": [1, ... , 140]
  }
]


Kohde: Infrastruktuuri (TpInfrastructure)
Metodi: get-infrastructures-by-urns (getInfrastructuresByUrns)
Selitys: palauttaa listan Infrastruktuureja annettujen URN-tunnisteiden perusteella
UI: http://avaa.tdata.fi/api/jsonws?contextPath=/tupa-portlet&signature=%2Ftupa-portlet%2FInfrastructures%2Fget-infrastructures-by-urns-1-infrastructuresUrns
Parametrit: infrastruktuurien URN-tunnisteeet
Parametrityyppi: vaihtelevakokoinen lista merkkijonoja
URL-kyselyesimerkki infrastruktuureille, joiden URN-tunnisteet ovat "urn:nbn:fi:research-infras-201607251" ja "urn:nbn:fi:research-infras-201607251":

  1. curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Infrastructures/get-infrastructures-by-urns/infrastructures-urns/%22urn%3Anbn%3Afi%3Aresearch-infras-201607251%22%2C%20%22urn%3Anbn%3Afi%3Aresearch-infras-201607253%22
  2. curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Infrastructures/get-infrastructures-by-urns/infrastructures-urns/'urn%3Anbn%3Afi%3Aresearch-infras-201607251'%2C%20'urn%3Anbn%3Afi%3Aresearch-infras-201607253'

Vastaus:
[
  {
    "contactsIds": [26, 27],
    "country": "FI",
    "id": 1,
    "infrastructuresIds": [18],
    "isni": "0000 0001 2198 1512",
    "motherOrganisationsIds": 0,
    "name_EN": "University of Turku",
    "name_FI": "Turun yliopisto",
    "servicesIds": [119, ... , 125]
  },
  {
    "contactsIds": [1, ... , 40],
    "country": "GB",
    "id": 3,
    "infrastructuresIds": [1, 17, 21],
    "isni": "",
    "motherOrganisationsIds": 0,
    "name_EN": "United Kingdom",
    "name_FI": "Yhdistynyt kuningaskunta",
    "servicesIds": [1, ... , 140]
  }
]

 

Kohde: Palvelu (TpServize)
Metodi: get-services-by-location (getServicesByLocation)
Selitys: palauttaa listan Palveluita, joiden sijaintipaikka on arviolta 1 km säteellä annetuista koordinaateista (riippuen palvelun sijainnista).
UI: http://avaa.tdata.fi/api/jsonws?contextPath=/tupa-portlet&signature=%2Ftupa-portlet%2FServices%2Fget-services-by-location-2-latitude-longitude
Parametrit: palvelun sijainnin leveyspiiri, palvelun sijainnin pituuspiiri
Parametrien tyypit: leveyspiiri kaksoistarkkuuksisena liukulukuna (double), pituuspiiri kaksoistarkkuuksisena liukulukuna (double)
URL-kyselyesimerkki palveluille, joiden sijainti on lähellä koordinaatteja "60.175538000000000000" ja "24.955310000000000000":

  1. curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Services/get-services-by-location/latitude/60.175538000000000000/longitude/24.955310000000000000

Vastaus:
[
  {
    "address": "Kaikukatu 4",
    "city": "Helsinki",
    "contactsIds": [3, 67],
    "description_EN": "Consortium acquiring centrally scholarly journals, books, reference books and databases in electronic format",
    "description_FI": "Konsortio, joka hankkii keskitetysti tieteellisiä e-lehtiä, e-kirjoja, hakuteoksia ja tietokantoja",
    "id": 8,
    "infrastructuresIds": [3],
    "lat": 60.182538,
    "locationTypes": [],
    "lon": 24.96031,
    "name_EN": "Acquisition of electronic publications",
    "name_FI": "Verkkoaineistojen hankinta",
    "organisationsIds": [4, 7],
    "serviceTypes": [],
    "url": "http://www.nationallibrary.fi/en/libraries/finelib.html"
  }
]


Kohde: Yhteystieto (TpContact)
Metodi: get-all-contacts (getAllContacts)
Selitys: palauttaa kaikki Yhteystiedot listana
UI: http://avaa.tdata.fi/api/jsonws?contextPath=/tupa-portlet&signature=%2Ftupa-portlet%2FContacts%2Fget-all-contacts-0
Parametrit: ei parametreja
URL-kyselyesimerkki kaikille saatavilla oleville Yhteystiedoille:

  1.     curl http://avaa.tdata.fi/api/jsonws/tupa-portlet.Contacts/get-all-contacts

Vastaus:
[
  {
    "description_EN": "",
    "description_FI": "",
    "email": "erja.esimerkki@yliopisto.fi",
    "firstName": "Erja",
    "id": 1,
    "infrastructuresIds": [1],
    "lastName": "Esimerkki",
    "organisationsIds": [2, 3],
    "phone": "",
    "servicesIds": [1, 2, 3, 4, 5],
    "title": "professori",
    "url": ""
  },
  ... ,
  {
    "description_EN": "",
    "description_FI": "",
    "email": "eini.esimerkki@university.fi",
    "firstName": "Eini",
    "id": 80,
    "infrastructuresIds": [15],
    "lastName": "Esimerkki",
    "organisationsIds": [
      4
    ],
    "phone": "040-653 1133",
    "servicesIds": [89, 90, 91, 92, 93, 94, 95, 96, 97],
    "title": "Johtaja",
    "url": ""
  }
]