Etsin rajapinta

Etsin-palvelua on mahdollista käyttää rajapinnan eli APIn yli (API = Application Programming Interface). Rajapinta sijaitsee osoitteessa https://etsin.avointiede.fi/api/3.

Etsimellä on myös OAI-PMH-rajapinta, josta enemmän tämän sivun lopussa.

Etsin tukee CKAN API -rajapintakomentoja, joiden kautta voit hakea, lisätä ja muokata aineistoja. Löydät rajapintakäyttöön tarvittavan API-avaimesi profiilivalikon Etsimen (etsin.avointiede.fi) Omat aineistot -linkin takaa, kun olet ensin kirjautunnut Etsimeen Haka-tunnuksellasi.

Etsin mahdollistaa myös aineiston muokkaajien ylläpidon rajapinnan kautta kutsuilla dataset_editor_add ja dataset_editor_delete. Lisätessäsi aineistolle muokkaajan anna kutsulle attribuutit: name (tietoaineiston nimi), role (yleisimmin 'editor') sekä username (sisäänkirjautumisen käyttäjätunnus). Huomaa että rajapinnan kautta saa annettua jossain määrin laajempaa roolitusta web-käyttöliittymään verrattuna, esimerkiksi 'agent' -kenttään voi liittää erilaisia rooleja ja tekijälle voi antaa URL:n joka myös näkyy aineiston katselusivulla.

Etsimen metatietomalli on huomattavasti monipuolisempi kuin CKAN-ohjelmiston perustietomalli. Sen vuoksi rajapintakäyttäjän on syytä tutustua Etsimen tietomallin dokumentaatioon ja alla annettuun esimerkkiin aineiston syöttämisestä rajapintakutsulla.

API-esimerkki

 
Kuvaus pids-kentän arvo
Aineistolla ei ole pysyvää tunnistetta Tässä tapauksessa koko kenttää ei tarvita. Etsin generoi primary-tyyppisen tunnisteen automaattisesti puolestasi.
Aineistolla on pysyvä tunniste, esim URN, DOI tms [{"id": "http://doi.org/xyz", "type": "primary"}]
Aineistolla ei ole tunnistetta, mutta siitä on olemassa edellinen versio, jolla on tunniste. Aineistojen versioiden suhdetta kuvataan Etsimessä inNewVersionOf tai isPreviousVersionOf relaatioilla [{"id": "urn:nbn:fi:org-xyz", "type": "relation", "relation": "isNewVersionOf"}]
Aineistolla on tunniste. Esimerkkitapauksessa uusi aineisto on osa toista aineistoa. Hierarkkisen suhteen aineiston osien välillä voi kuvata relaatioilla isPartOf tai hasPart [{"id": "http://doi.org/xyz", "type": "primary"}, {"id": "urn:nbn:fi:org-xyz", "type": "relation", "relation": "isPartOf"}]
     


Huomaa, että parametrina on organisaation id, joka noudettiin aiemmin organization_show -funktiolla.

 

OAI-PMH-rajapinta

Etsimen aineistot ovat tarjolla haravoitavaksi myös OAI-PMH-rajapinnan kautta https://etsin.avointiede.fi/oai. Voit noutaa aineistoja seuraavasti:

  • tiedot olemassa olevista aineistojen ryhmittelyistä (ListSets, vain organisaatioiden mukaiset joukot)
  • aineistojen otsikot (ListIdentifiers)
  • yksittäisen aineiston (GetRecord)
  • kaikki aineistot (ListRecords)

Esimerkkejä:

Komennot ListSets, ListIdentifiers ja ListRecords pätkivät vastauksen. Seuraavan palan vastausta saat antamalla edellisen vastauksen lopusta löytyvän resumptionToken:in uuden pyynnön parametrina.

Esimerkki:
 

 

Seuraavilla parametreilla pystyt rajaamaan noudettavia aineistoja: