ONKI HTTP API (v2)

Yleistä rajapinnasta

ONKI-palvelun HTTP-rajapinta on vielä testausvaiheessa, joten sen käyttöä ei suositella tuotantojärjestelmissä. Osaa metodeista ei ole optimoitu/viimeistelty, joten kannattaa varautua viiveisiin rajapinnan vastauksissa. Lisäksi rajapinnan metodit saattavat muuttua varoittamatta. Rajapinnan kehitysehdotuksia ja ongelmaraportteja otetaan vastaan sähköpostitse: seco-ysofi@tkk.fi. Ontologiakohtaista palautetta voit antaa avaamalla ONKI-selaimen, klikkaamalla Palaute ja valitsemalla halutun ontologian.

HTTP-rajapintaa käytetään tekemällä HTTP GET -pyyntöjä URL-osoitteisiin, jotka ovat muotoa:
http://onki.fi/key-[ONKI-AVAIMESI]/api/v2/http/[METODIRYHMÄ]/[METODIN NIMI][?PARAMETRIT]


HTTP-rajapinnan vastaukset ovat JSON-muodossa.

General information about the API

The HTTP API of the ontology service ONKI is still in the testing phase, so using it in production systems is not encouraged yet. Some of the methods are not optimized, so please delays in responses. Also, the methods of the interface may be changed without notice. Improvement ideas and problem reports can be sent via email: seco-ysofi@tkk.fi. To give ontology specific feedback, go to ONKI Browser, click on Feedback and select the ontology.

The HTTP API is used by making HTTP GET requests to URLs which are formed as follows:
http://onki.fi/key-[YOUR ONKI KEY]/api/v2/http/[METHOD GROUP]/[METHOD_NAME][?PARAMETERS]


The responses of the HTTP API are in JSON format.

Rajapinnan metodit Methods of the API

Repositoriometodit Repository methods

Ontologiametodit Ontology methods

Palvelimen tilatiedot The status information of the server

Ontologian metatiedot The ontology metadata

Käsitteen haku Concept search

Käsitteen hierarkia Concept hierarchy

Käsitteen tiedot Concept information

Ontologian hakemisto / yleisnäkymä Ontology directory

Repositoriometodit Repository methods

search

kuvaus: käsitteen haku koko repositoriosta description: concept search from the whole repository
parametrit parameters : vastaus response : metatietoa hausta ja lista hakutuloksista, joilla nimi johon haku täsmäsi (prefLabel/altLabel) ja URI metadata about the query and list of search results with label matched (prefLabel/altLabel) and URI

languages

kuvaus: kielet joilla ontologian käsitteiden nimiä on saatavissa repositoriosta description: available languages of concept labels in the ontology repository
parametrit parameters : -
vastaus response : lista kielikoodeista list of language codes

ontologies

kuvaus: palauttaa repositorion ontologioiden nimet ja muuta metatietoa description: returns the names and metadata about the ontologies in the repository
parametrit parameters : -
vastaus response : lista ontologioista list of ontologies

Ontologiametodit Ontology methods

Pakolliset parametrit on lihavoitu. The required parameters are marked as bold.

Palvelimen tilatiedot

ping

kuvaus: testataan onko palvelin käynnissä description: testing if the server is running
parametrit parameters : -
vastaus response : "1"

Ontologian metatiedot The ontology metadata

getMetadata

kuvaus: metatietoa ontologiasta description: metadata about the ontology
parametrit parameters : vastaus response : metatietoa ontologiasta metadata about the ontology

getAvailableLanguages

kuvaus: kielet joilla ontologian käsitteiden nimiä on saatavissa description: available languages of concept labels in the ontology
parametrit parameters : -
vastaus response : lista kielikoodeista list of language codes

getAvailableTypeUris

kuvaus: ontologiassa olevien käsitteiden tyyppien URI-tunnisteet description: available types of the concepts in the ontology
parametrit parameters : -
vastaus response : lista käsitetyyppien URI-tunnisteita list of concept type URIs

Käsitteen haku Concept search

kuvaus: käsitteen haku description: concept search
parametrit parameters : vastaus response : metatietoa hausta ja lista hakutuloksista, joilla nimi johon haku täsmäsi (prefLabel/altLabel) ja URI metadata about the query and list of search results with label matched (prefLabel/altLabel) and URI

Käsitteen hierarkia Concept hierarchy

getConceptHierarchy

kuvaus: käsitteen hierkia (ylä-/ala-/vieruskäsitteet) description: concept hierarchy (superconcepts/subconcepts/sibling concepts)
parametrit parameters : vastaus response : lista hierarkiapuun solmuista, joilla URI, nimi, yläkäsitteen URI, sisennystaso (käyttöliittymän tekemisen helpottamiseksi) list of hierarchy tree nodes with URI, label, superconcept URI, indent level (for helping user interface generation)

getHierarchyRoots

kuvaus: käsitteen hierarkian juuret, tai jos URIa ei anneta, kaikki ontologian käsitteet, joilla ei yläkäsitettä description: the roots of a concept's hierarchy, or if the URI is not given, all the concepts of the ontology which have no superconcepts
parametrit parameters : vastaus response : lista käsitteistä, joilla URI ja nimi list of concepts with URI and label

Käsitteen tiedot Concept information

getProperties

kuvaus: käsitteen tiedot (RDF properties) description: properties of the concept
parametrit parameters : vastaus response : lista ominaisuus-arvo-pareista, joilla ominaisuuden URI, nimi sekä arvon URI ja nimi (jos kyseessä on resurssiviittaus) tai arvo literaalina ja kielikoodi (jos kyseessä literaali) list of property-value pairs with property URI, label and object URI and label (in case of resource value) or literal and languge code (in case of literal value)

getLabels

kuvaus: käsitteen nimet description: labels of the concept
parametrit parameters : vastaus response : lista nimistä, joilla itse nimen lisäksi kielikoodi, ominaisuuden URI ja ominaisuuden nimi list of labels with language code, property URI and property label

getAltLabels

kuvaus: käsitteen vaihtoehtoiset (korvatut) nimet description: alternative labels of the concept
parametrit parameters : vastaus response : lista vaihtoehtoisista nimistä, joilla itse vaihtoehtoisen nimen lisäksi kielikoodi, ominaisuuden URI ja ominaisuuden nimi list of alternative labels with language code, property URI and property label

getDescriptions

kuvaus: käsitteen kuvaukset description: descriptions of the concept
parametrit parameters : vastaus response : lista kuvauksista, joilla itse kuvauksen lisäksi kielikoodi, ominaisuuden URI ja ominaisuuden nimi list of descriptions with language code, property URI and property label

getEquivalentConcepts

kuvaus: ekvivalentit käsitteet description: equivalent concepts
parametrit parameters : vastaus response : lista ominaisuus-käsite-pareista, joilla ominaisuuden URI, nimi sekä käsitteen URI ja nimi list of property-concept pairs with property URI, label and concept URI and label

getRelatedConcepts

kuvaus: assosiatiiviset käsitteet / rinnakkaiskäsitteet description: associative concepts / related concepts
parametrit parameters : vastaus response : lista ominaisuus-käsite-pareista, joilla ominaisuuden URI, nimi sekä käsitteen URI ja nimi list of property-concept pairs with property URI, label and concept URI and label

getGroups

kuvaus: ryhmät joihin käsite kuuluu description: groups the concept belongs to
parametrit parameters : vastaus response : lista ominaisuus-ryhmä-pareista, joilla ominaisuuden URI, nimi sekä ryhmän URI ja nimi list of property-group pairs with property URI, label and group URI and label

getTypes

kuvaus: käsitteen tyypit description: types of the concept
parametrit parameters : vastaus response : lista ominaisuus-tyyppi-pareista, joilla ominaisuuden URI, nimi sekä tyypin URI ja nimi list of property-type pairs with property URI, label and type URI and label

getFullPresentation

kuvaus: kaikki oleellinen tieto käsitteestä (yhdistää metodit getProperties, getLabels jne. yhteen metodikutsuun) description: all the relevant information about the concept (merges methods getProperties, getLabels etc. in a single method call)
parametrit parameters : vastaus response : lista metodinimi-vastaus-pareista list of method name - response pairs

Ontologian hakemisto/yleisnäkymä Ontology directory

getDirectory

kuvaus: ontologian hakemisto - aakkosellinen hakemisto, ryhmät (esim. YSA) tai ylätason käsitteet (SKOS-sanastot) description: ontology directory - alphabetical index, groups (e.g. YSA) or topconcepts (SKOS vocabularies)
parametrit parameters : vastaus response : lista hakemistoelementeistä (ryhmä/ylätason käsite/kirjain), joilla URI (ryhmä/ylätason käsite), nimi, hakemistoelementtiin kuuluvien käsitteiden lkm sekä lista siihen kuuluvista käsitteistä list of directory elements (group, topconcept, alphabet) with URI (group/topconcept), label, amount of concepts beloging to the directory element and a list of belonging concepts