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]
- ONKI-AVAIMESI on ONKI-palveluun rekisteröityessäsi saamasi avain
- METODIRYHMÄ on joko "repo" (koko repositoriota koskevat HTTP-pyynnöt) tai "onto/[ONTOLOGIATUNNISTE]" (tiettyyn ontologiaan kohdistuvat pyynnöt, esim. "onto/yso" kohdistuu Yleiseen suomalaiseen ontologiaan YSO:on)
- METODIN_NIMI on metodin nimi, esim. "getProperties"
- PARAMETRIT ovat metodille annettavat parametrit, esim. "u=http://www.yso.fi/onto/yso/p17093&l=fi"
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]
- YOUR ONKI KEY is the key received when registering to the ONKI service
- METHOD GROUP is either "repo" (for repository wide requests) or "onto/[ONTOLOGY ID]" (for ontology specific requests, where ONTOLOGY ID is the unique identifier of the ontology, e.g. "yso" (The Finnish General Upper Ontology)
- METHOD_NAME is the name of the method, e.g. "getProperties"
- PARAMETERS are the parameters given to the method, e.g. "u=http://www.yso.fi/onto/yso/p17093&l=fi"
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
kuvaus: käsitteen haku koko repositoriosta
description: concept search from the whole repository
parametrit
parameters
:
- q - hakumerkkijonoquery string
- l - hakukieliquery language
- qt - haun rajaus tietyntyyppisiin käsitteisiin (URI)restrict query to concept type (URI)
- qp - haun rajaus tietyn käsitteen alakäsitteisiin transitiivisesti (URI)restrict query to transitive subconcepts of a concept (URI)
- qg - haun rajaus tiettyyn ryhmään kuuluviin käsitteisiin (URI)restrict query to concepts in a group (URI)
- h - hakutulosten maksimimäärämaximum amount of search results
- s - aloita tulosjoukko hakutuloksesta nro (hakutulosten sivutusta varten)start result set from hit # (for paging)
- ac - sisällytä tulosjoukkoon hakumerkkijonolla alkavat käsitteet (totuusarvo: "true"/"false")include the concepts starting with the query string (boolean: true/false)
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
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
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
kuvaus: testataan onko palvelin käynnissä
description: testing if the server is running
parametrit
parameters
: -
vastaus
response
: "1"
Ontologian metatiedot
The ontology metadata
kuvaus: metatietoa ontologiasta
description: metadata about the ontology
parametrit
parameters
:
vastaus
response
:
metatietoa ontologiasta
metadata about the ontology
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
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
:
- q - hakumerkkijonoquery string
- l - hakukieliquery language
- qt - haun rajaus tietyntyyppisiin käsitteisiin (URI)restrict query to concept type (URI)
- qp - haun rajaus tietyn käsitteen alakäsitteisiin transitiivisesti (URI)restrict query to transitive subconcepts of a concept (URI)
- qg - haun rajaus tiettyyn ryhmään kuuluviin käsitteisiin (URI)restrict query to concepts in a group (URI)
- h - hakutulosten maksimimäärämaximum amount of search results
- s - aloita tulosjoukko hakutuloksesta nro (hakutulosten sivutusta varten)start result set from hit # (for paging)
- ac - sisällytä tulosjoukkoon hakumerkkijonolla alkavat käsitteet (totuusarvo: "true"/"false")include the concepts starting with the query string (boolean: true/false)
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
kuvaus: käsitteen hierkia (ylä-/ala-/vieruskäsitteet)
description: concept hierarchy (superconcepts/subconcepts/sibling concepts)
parametrit
parameters
:
- u - käsitteen URIconcept URI
- l - kielilanguage
- p - yläkäsitteiden tasojen lkm: 0..n; 1 == vain suorat yläkäsitteet, 2 == suorat yläkäsitteet ja niiden suorat yläkäsitteet, jne.the amount of superconcept levels: 0..n; 1 == only direct superconcepts, 2 == direct superconcepts and their direct superconcepts, etc.
- c - alakäsitteiden tasojen lkm: 0..nthe amount of subconcept levels: 0..n
- s - vieruskäsitteet: 0..1sibling concepts: 0..1
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)
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
:
- u - käsitteen URIconcept URI
- l - kielilanguage
vastaus
response
:
lista käsitteistä, joilla URI ja nimi
list of concepts with URI and label
Käsitteen tiedot
Concept information
kuvaus: käsitteen tiedot (RDF properties)
description: properties of the concept
parametrit
parameters
:
- u - käsitteen URIconcept URI
- l - kielilanguage
- pl - ominaisuuden nimen kielilanguage of the property label
- p - ominaisuuden URI, jos halutaan vain tietty ominaisuusproperty URI, if only a specific property is wanted
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)
kuvaus: käsitteen nimet
description: labels of the concept
parametrit
parameters
:
- u - käsitteen URIconcept URI
- l - kielilanguage
- pl - ominaisuuden nimen kielilanguage of the property label
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
kuvaus: käsitteen vaihtoehtoiset (korvatut) nimet
description: alternative labels of the concept
parametrit
parameters
:
- u - käsitteen URIconcept URI
- l - kielilanguage
- pl - ominaisuuden nimen kielilanguage of the property label
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
kuvaus: käsitteen kuvaukset
description: descriptions of the concept
parametrit
parameters
:
- u - käsitteen URIconcept URI
- l - kielilanguage
- pl - ominaisuuden nimen kielilanguage of the property label
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
kuvaus: ekvivalentit käsitteet
description: equivalent concepts
parametrit
parameters
:
- u - käsitteen URIconcept URI
- l - kielilanguage
- pl - ominaisuuden nimen kielilanguage of the property label
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
kuvaus: assosiatiiviset käsitteet / rinnakkaiskäsitteet
description: associative concepts / related concepts
parametrit
parameters
:
- u - käsitteen URIconcept URI
- l - kielilanguage
- pl - ominaisuuden nimen kielilanguage of the property label
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
kuvaus: ryhmät joihin käsite kuuluu
description: groups the concept belongs to
parametrit
parameters
:
- u - käsitteen URIconcept URI
- l - kielilanguage
- pl - ominaisuuden nimen kielilanguage of the property label
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
kuvaus: käsitteen tyypit
description: types of the concept
parametrit
parameters
:
- u - käsitteen URIconcept URI
- l - kielilanguage
- pl - ominaisuuden nimen kielilanguage of the property label
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
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
:
- u - käsitteen URIconcept URI
- l - kielilanguage
- pl - ominaisuuden nimen kielilanguage of the property label
vastaus
response
:
lista metodinimi-vastaus-pareista
list of method name - response pairs
Ontologian hakemisto/yleisnäkymä
Ontology directory
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
:
- t - hakemiston tyyppi: "groups", "topconcepts" tai "alphabetical"; oletus on "groups",
jos ontologialla on määritelty ryhmät; "topconcepts", jos ontologia on SKOS-sanasto
ja ylätason käsitteitä on maksimissaan 50; muutoin "alphabetical"
directory type: "groups", "topconcepts" or "alphabetical"; default value is "groups",
if the ontology contains concept groups; "topconcepts", if the ontology is a SKOS
vocabulary and there is maximum of 50 topconcepts; otherwise "alphabetical"
- m - kuinka monta hakemistoelementteihin (ryhmä/ylätason käsite/kirjain)
kuuluvaa käsitettä palautetaan: 0..n
amount of concepts returned per a directory element (group, topconcept, alphabet): 0..n
- l - kielilanguage
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