ONKI REST API (beta)

General information about the API

The REST 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 the feedback form of the ONKI service.

The REST API is used by making HTTP GET requests to URLs which are formed as follows:
http://www.yso.fi/key-[YOUR_ONKI_KEY]/onki/[ONTOLOGY_ID]/rest/[METHOD_NAME][?][PARAMETERS]

• YOUR_ONKI_KEY is the key received when registering to the ONKI service
• 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 REST API are in JSON format.

Methods of the API

The status information of the server:

• ping

The ontology metadata:

• getMetadata
• getAvailableLanguages
• getAvailableTypeUris

Concept search:

• search

Concept hierarchy:

• getConceptHierarchy
• getHierarchyRoots

Concept information:

• getProperties
• getLabels
• getAltLabels
• getDescriptions
• getEquivalentConcepts
• getRelatedConcepts
• getGroups
• getTypes
• getFullPresentation

Ontology directory:

• getDirectory

The required parameters are marked as bold.

The status information of the server

ping

description: testing: is the server running
parameters: -
response: "1"

The ontology metadata

getMetadata

description: metadata about the ontology
parameters:

• l - language

response: metadata about the ontology

getAvailableLanguages

description: available languages of concept labels in the ontology
parameters: -
response: list of language codes

getAvailableTypeUris

description: available types of the concepts in the ontology
parameters: -
response: list of concept type URIs

Concept search

search

description: concept search
parameters:

• q - query string
• l - query language
• qt - restrict query to concept type (URI)
• qp - restrict query to transitive subconcepts of a concept (URI)
• qg - restrict query to concepts in a group (URI)
• h - maximum amount of search results
• s - start result set from hit # (for paging)
• ac - include the concepts starting with the query string (boolean: true/false)

response: metadata about the query and list of search results with label matched (prefLabel/altLabel) and URI

Concept hierarchy

getConceptHierarchy

description: concept hierarchy (superconcepts/subconcepts/sibling concepts)
parameters:

• u - concept URI
• l - language
• p - the amount of superconcept levels: 0..n; 1 == only direct superconcepts, 2 == direct superconcepts and their direct superconcepts, etc.
• c - the amount of subconcept levels: 0..n
• s - sibling concepts: 0..1

response: list of hierarchy tree nodes with URI, label, superconcept URI, indent level (for helping user interface generation)

getHierarchyRoots

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
parameters:

• u - concept URI
• l - language

response: list of concepts with URI and label

Concept information

getProperties

description: properties of the concept
parameters:

• u - concept URI
• l - language
• p - property URI, if only a specific property is wanted

response: 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

description: labels of the concept
parameters:

• u - concept URI
• l - language
• pl - language of the property label

response: list of labels with language code, property URI and property label

getAltLabels

description: alternative labels of the concept
parameters:

• u - concept URI
• l - language
• pl - language of the property label

response: list of alternative labels with language code, property URI and property label

getDescriptions

description: descriptions of the concept
parameters:

• u - concept URI
• l - language
• pl - language of the property label

response: list of descriptions with language code, property URI and property label

getEquivalentConcepts

description: equivalent concepts
parameters:

• u - concept URI
• l - language

response: list of property-concept pairs with property URI, label and concept URI and label

getRelatedConcepts

description: associative concepts / related concepts
parameters:

• u - concept URI
• l - language

response: list of property-concept pairs with property URI, label and concept URI and label

getGroups

description: groups the concept belongs to
parameters:

• u - concept URI
• l - language

response: list of property-group pairs with property URI, label and group URI and label

getTypes

description: types of the concept
parameters:

• u - concept URI
• l - language

response: list of property-type pairs with property URI, label and type URI and label

getFullPresentation

description: all the relevant information about the concept (merges methods getProperties, getLabels etc. in a single method call)
parameters:

• u - concept URI
• l - language
• pl - language of the property label

response: list of method name - response pairs

Ontology directory

getDirectory

description: ontology directory - alphabetical index, groups (e.g. YSA) or topconcepts (SKOS vocabularies)
parameters:

• t - 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 - amount of concepts returned per a directory element (group, topconcept, alphabet): 0..n
• l - language

response: 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