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-help@list.aalto.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-help@list.aalto.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

Ontologiametodit Ontology methods

Palvelimen tilatiedot The status information of the server

ping

Ontologian metatiedot The ontology metadata

getMetadata
getAvailableLanguages
getAvailableTypeUris

Käsitteen haku Concept search

Repositoriometodit Repository methods

search

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

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 :

l - kielilanguage

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

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)

Käsitteen hierarkia Concept hierarchy

getConceptHierarchy

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)

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 :

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

getProperties

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)

getLabels

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

getAltLabels

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

getDescriptions

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

getEquivalentConcepts

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

getRelatedConcepts

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

getGroups

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

getTypes

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

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 :

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

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 :

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

ONKI HTTP API (v2)

Yleistä rajapinnasta

General information about the API

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

languages

ontologies

Ontologiametodit Ontology methods

Palvelimen tilatiedot

ping

Ontologian metatiedot The ontology metadata

getMetadata

getAvailableLanguages

getAvailableTypeUris

Käsitteen haku Concept search

search

Käsitteen hierarkia Concept hierarchy

getConceptHierarchy

getHierarchyRoots

Käsitteen tiedot Concept information

getProperties

getLabels

getAltLabels

getDescriptions

getEquivalentConcepts

getRelatedConcepts

getGroups

getTypes

getFullPresentation

Ontologian hakemisto/yleisnäkymä Ontology directory

getDirectory