This API documentation has been replaced by the Swagger description in Skosmos 1.6 and interactive API documentation generated from the Swagger description using the swagger-ui tool. The below specification is for historical purposes only.

---

This document specifies the REST API (v1) in Skosmos v0.4-v1.6 and earlier versions of ONKI Light.

Note: Not all of this API has yet been implemented! The missing parts have been labeled as NOT IMPLEMENTED in the documentation below.

The Skosmos REST API is a read-only interface to the data stored in the vocabulary server.

The URL namespace is the URL of the Skosmos instance, e.g.

• http://api.finto.fi (at the National Library of Finland, running the latest Skosmos release)
• http://light.onki.fi (at the SeCo research group)

REST URLs begin with /rest/v1.

If mandatory parameters are missing, a 400 Bad Request HTTP error code will be returned.

Most methods return the data as UTF-8 encoded JSON-LD, served using the application/json MIME type. The data consists of a single JSON object which includes JSON-LD context information (in the @context field) and one or more fields which contain the actual data.

Some methods (data) return other formats (RDF/XML, Turtle, RDF/JSON) with the appropriate MIME type.

The API supports Cross-Origin Resource Sharing by setting the Access-Control-Allow-Origin HTTP header to "*" for all requests.

The API supports the JSONP convention of appending a callback parameter to any URL. The returned data will then be wrapped in a JavaScript function call using the function name provided as the callback parameter value. JSONP wrapped data will be served using the application/javascript MIME type.

Parameters:

• lang (required): language of labels, e.g. "en" or "fi"

Returns a list of vocabularies on the server.

The returned object contains a vocabularies field containing an array of objects with the following fields:

Field	Required?	Description
uri	required	Relative URI of vocabulary
id	required	Vocabulary identifier
title	required	Vocabulary title

Example: http://api.finto.fi/rest/v1/vocabularies?lang=en

Parameters:

• query (required): the term to search for
• lang (optional): search language, e.g. "en" or "fi"
• labellang (optional): language of returned labels, e.g. "en" or "fi" (new in Skosmos 0.4)
• vocab (optional): vocabulary to limit search to, e.g. "yso"
• type (optional): limit search to concepts of the given type, e.g. 'skos:Concept' or 'http://www.yso.fi/onto/ysa-meta/GeographicalConcept'. Starting with Skosmos 0.7, you can specify multiple types (OR semantics) as a space-separated list.
• parent (optional): limit search to concepts which have the given concept (specified by URI) as parent in their transitive broader hierarchy
• group (optional): limit search to concepts in the given group (specified by URI)
• fields (optional): space-separated list of extra fields to include in the results. Supported values: "broader". After 1.6 update: "prefLabel" (Gives you all the languages available), "related" or any other skos property.
• unique (optional): boolean flag to indicate that each concept should be returned only once, instead of returning all the different ways it could match (for example both via prefLabel and altLabel). New in Skosmos 1.4

Returns a list of search results in JSON-LD format. If decoded into RDF, the result is a vocabulary fragment expressed as SKOS. See the vocabulary-specific search method below for more details on the query language and the result format.

Example: http://api.finto.fi/rest/v1/search?query=cat*&lang=en

Parameters:

• uri (mandatory): URI of the concept whose data to return
• format (optional): the MIME type of the serialization format, e.g. "text/turtle" or "application/rdf+xml"

Returns the RDF data of the requested concept from all vocabularies merged together. If the format is not specified, HTTP content negotiation (based on the Accept header) is used to determine a suitable serialization format.

Example: http://api.finto.fi/rest/v1/data?uri=http://www.yso.fi/onto/yso/p21639

NOTE: Introduced in Skosmos v0.5.

Parameters:

• lang (required): language of labels, e.g. "en" or "fi".

Return information about the types (classes) of objects contained in all the vocabularies, including possible subclasses of SKOS Concept, Collection and other standard classes, in JSON-LD format.

The returned object contains a types field containing an array of objects with the following fields:

Field	Required?	Description
uri	required	Concept scheme URI
label	optional	Label of type
superclass	optional	URI of the superclass type, which this type is an extension/specialization of

Example: http://api.finto.fi/rest/v1/koko/types

These methods exist on a single vocabulary. The URL starts with /rest/<vocid>/ where <vocid> is the vocabulary identifier.

Parameters:

• lang (optional): language of labels, e.g. "en" or "fi". If not given, the default language of the vocabulary will be used.

Return general information about the vocabulary in JSON-LD format. The returned information includes:

• vocabulary identifier and label
• included languages
• default language
• concept schemes

The returned object contains the following fields:

Field	Required?	Description
id	required	ID of vocabulary
title	required	Title of vocabulary
defaultLanguage	required	Default language of vocabulary
languages	required	Array of languages supported by vocabulary
conceptschemes	required	Array of concept schemes within vocabulary

Each concept scheme object has the following fields:

Field	Required?	Description
uri	required	Concept scheme URI
type	required	Type of object (currently always "skos:ConceptScheme")
label	optional	Label of concept scheme (rdfs:label)
prefLabel	optional	Preferred label of concept scheme (skos:prefLabel)
title	optional	Title of concept scheme (dc:title)

Note that depending on how the concept scheme is defined within the vocabulary, it may have zero or more of the fields label, prefLabel and title. Users of this API need to check all three fields if they want to have a human-readable label for the concept scheme.

Example: http://api.finto.fi/rest/v1/yso/

Parameters:

• lang (optional): language of labels, e.g. "en" or "fi". If not given, the default language of the vocabulary will be used.

Return information about the types (classes) of objects contained in the vocabulary, including possible subclasses of SKOS Concept, Collection and other standard classes, in JSON-LD format.

The returned object contains a types field containing an array of objects with the following fields:

Field	Required?	Description
uri	required	Concept scheme URI
label	optional	Label of type
superclass	optional	URI of the superclass type, which this type is an extension/specialization of

Example: http://api.finto.fi/rest/v1/koko/types

Parameters:

• lang (optional): language of labels, e.g. "en" or "fi"
• scheme (optional): concept scheme whose top concepts to return. If not given, the default concept scheme of the vocabulary will be used.

Return the top concepts of the vocabulary in JSON-LD format. If decoded into RDF, the result is a vocabulary fragment expressed as SKOS.

The returned object contains a topconcepts field containing an array of objects with the following fields:

Field	Required?	Description
uri	required	URI of concept
label	optional	Label of concept
notation	optional	Notation of concept
hasChildren	required	Boolean value indicating whether the concept has narrower concepts

Example: http://api.finto.fi/rest/v1/yso/topConcepts?lang=fi

Parameters:

• format (optional): the MIME type of the serialization format, e.g. "text/turtle" or "application/rdf+xml" . Introduced in Skosmos 0.7.

Returns the RDF data of the vocabulary. If the format is not specified, HTTP content negotiation (based on the Accept header) is used to determine a suitable serialization format from among the available ones.

Example: http://api.finto.fi/rest/v1/yso/data

Parameters:

• query (mandatory): the term to search for
• lang (optional): search language, e.g. "en" or "fi"
• type (optional): limit search to concepts of the given type, e.g. 'skos:Concept' or http://www.yso.fi/onto/ysa-meta/GeographicalConcept. Starting with Skosmos 0.7, you can specify multiple types (OR semantics) as a space-separated list.
• parent (optional): limit search to concepts which have the given concept (specified by URI) as parent in their transitive broader hierarchy
• group (optional): limit search to concepts in the given group (specified by URI)
• maxhits (optional): Maximum number of results to return. If not given, maxhits will default to 100. (default settable in config.inc)
• offset (optional): offset where to start in the result set, useful for paging the result. If not given, defaults to 0.
• fields (optional): space-separated list of extra fields to include in the results. Supported values: "broader". After 1.6 update: "prefLabel" (Gives you all the languages available), "related" or any other skos property.
• unique (optional): boolean flag to indicate that each concept should be returned only once, instead of returning all the different ways it could match (for example both via prefLabel and altLabel). New in Skosmos 1.4

Returns a list of search results in JSON-LD format. The search is performed as a case-insensitive pattern, where an asterisk (*) may be used as wildcard. E.g. "cat*" may return results such as "CATCH-22" and "categorization". If decoded into RDF, the result is a vocabulary fragment expressed as SKOS.

The returned object contains a results field containing an array of objects with the following fields:

Field	Required?	Description
uri	required	Concept URI
vocab	required	ID of vocabulary where concept was found
localname	optional	Local name of concept (last part of URI). Missing if the concept is external to the vocabulary (i.e. not inside vocabulary namespace).
prefLabel	required	Preferred label of concept
altLabel	optional	Alternate label of concept, if found via that label
exvocab	optional	If the concept was external to the vocabulary, the identifier of the real vocabulary where it belongs
broader	optional	Broader concepts of the concept, as a list of objects with the fields uri and prefLabel. Only returned when fields=broader parameter is used. Labels for broader concepts are returned if the labellang parameter has been set.

Example: http://api.finto.fi/rest/v1/ysa/search?query=cat*&lang=fi

Parameters:

• label (required): label to look up in the vocabulary, e.g. "cat"
• lang (optional): search language, e.g. "en" or "fi"

If the lang parameter is given, only labels in the requested language are considered when matching. Otherwise, labels in any language are considered.

The search is performed as a label match with the following precedence:

1. exact match on preferred label
2. case-insensitive match on preferred label
3. exact match on alternate label
4. case-insensitive match on alternate label
5. exact match on hidden label NOT IMPLEMENTED
6. case-insensitive match on hidden label NOT IMPLEMENTED

If no match is found, a 404 Not Found HTTP error code will be returned instead.

See the vocabulary-specific search method for information about the format of returned data.

Returns the best matching concept(s) for the given label in JSON-LD format. In case the label matches several concepts with the same precedence, all of them are returned. If decoded into RDF, the result is a vocabulary fragment expressed as SKOS.

Example: http://api.finto.fi/rest/v1/ysa/lookup?label=kissat&lang=fi

Returns the number of skos:Concepts in the vocabulary.

Parameters:

• lang (optional): language to use for the vocabulary title, e.g. "en" or "fi". If not given, the default language of the vocabulary will be used.

The returned object contains the following fields:

Field	Required?	Description
id	required	identifier of vocabulary
title	required	title of the vocabulary
concepts	required	count object (see below)

The count object contains the following fields:

Field	Required?	Description
class	required	class/type of concepts (currently always "skos:Concept")
count	required	number of concepts as an integer value

Introduced in Skosmos 0.7.

Returns a list of label (skos:prefLabel, skos:altLabel and skos:hiddenLabel) counts in all the different languages.

Parameters:

• lang (optional): language to use for language names, e.g. "en" or "fi". If not given, only language tags will be returned

The returned object contains the following fields:

Field	Required?	Description
id	required	identifier of vocabulary
title	required	title of the vocabulary
languages	required	list of language objects (see below)

Each language object contains the following fields:

Field	Required?	Description
language	required	language code e.g. "fi" or "en"
literal	optional	language name e.g. "Finnish" or "English" (if lang parameter was used)
properties	required	list of property objects (see below)

Each property object contains the following fields:

Field	Required?	Description
property	required	property identifier, either "skos:prefLabel" or "skos:altLabel" or "skos:hiddenLabel"
labels	required	number of labels with the specified property in the given language

Introduced in Skosmos 0.7.

These methods exist for single concepts. Each takes a uri parameter specifying the concept that the method call applies to.

TODO: should the API support also short URLs such as /yso/p12345/broader ? These are nice, but cannot always be used (the vocabularies may contain URIs which use namespaces other than the default namespace).

Parameters:

• uri (mandatory): URI of the concept whose label to return
• lang (optional): Language of labels. If not given, the label is returned in the default language of the vocabulary.

NOTE: Introduced in ONKI Light v0.2.

Returns the preferred label of the requested concept in JSON-LD format. If decoded into RDF, the result is a vocabulary fragment expressed as SKOS.

The returned object contains the following fields:

Field	Required?	Description
uri	required	URI of concept
prefLabel	required	Preferred label of concept

Example: http://api.finto.fi/rest/v1/yso/label?uri=http://www.yso.fi/onto/yso/p19378&lang=en

Parameters:

• uri (mandatory): URI of the concept whose data to return
• format (optional): the MIME type of the serialization format, e.g. "text/turtle" or "application/rdf+xml"

Returns the RDF data of the requested concept. If the format is not specified, HTTP content negotiation (based on the Accept header) is used to determine a suitable serialization format.

Note: When no uri parameter is given, the whole vocabulary is requested instead. See the vocabulary-specific data method above.

Note: Since ONKI Light 0.2, JSON-LD is returned when format=application/json is requested. In previous versions, RDF/JSON serialization was used instead.

Example: http://api.finto.fi/rest/v1/yso/data?uri=http://www.yso.fi/onto/yso/p21639

Parameters:

• uri (mandatory): URI of the concept whose hierarchy to return
• lang (optional): Language of labels. If not given, labels are returned in the default language of the vocabulary.

Returns the broader concepts of the requested concepts in JSON-LD format. If decoded into RDF, the result is a vocabulary fragment expressed as SKOS.

The returned object contains a broader field containing an array of objects with the following fields:

Field	Required?	Description
uri	required	URI of concept
prefLabel	required	Preferred label of concept

Example: http://api.finto.fi/rest/v1/yso/broader?uri=http://www.yso.fi/onto/yso/p19378&lang=en

Parameters:

• uri (mandatory): URI of the concept whose hierarchy to return
• lang (optional): Language of labels. If not given, labels are returned in the default language of the vocabulary.
• limit (optional): Maximum number of results to return. If not given, limit will default to 1000.

Returns the full transitive broader hierarchy of the requested concepts, all the way up to top-level concepts, in JSON-LD format. If decoded into RDF, the result is a vocabulary fragment expressed as SKOS.

The returned object contains a broaderTransitive field containing an object having concept URIs as keys and objects with the following fields as values:

Field	Required?	Description
uri	required	URI of concept (same as key)
prefLabel	required	Preferred label of concept
broader	optional	Array of concepts (URIs) that are broader concepts of the current concept

Example: http://api.finto.fi/rest/v1/yso/broaderTransitive?uri=http://www.yso.fi/onto/yso/p19378&lang=en

Parameters:

• uri (mandatory): URI of the concept whose hierarchy to return
• lang (optional): Language of labels. If not given, labels are returned in the default language of the vocabulary.

Returns the narrower concepts of the requested concepts in JSON-LD format. If decoded into RDF, the result is a vocabulary fragment expressed as SKOS.

The returned object contains a narrower field containing an array of objects with the following fields:

Field	Required?	Description
uri	required	URI of concept
prefLabel	required	Preferred label of concept

Example: http://api.finto.fi/rest/v1/yso/narrower?uri=http://www.yso.fi/onto/yso/p19378&lang=en

Parameters:

• uri (mandatory): URI of the concept whose hierarchy to return
• lang (optional): Language of labels. If not given, labels are returned in the default language of the vocabulary.
• limit (optional): Maximum number of results to return. If not given, limit will default to 1000. (default settable in config.inc)

Returns the full transitive broader hierarchy of the requested concepts, all the way up to top-level concepts, in JSON-LD format. If decoded into RDF, the result is a vocabulary fragment expressed as SKOS.

The returned object contains a narrowerTransitive field containing an object having concept URIs as keys and objects with the following fields as values:

Field	Required?	Description
uri	required	URI of concept (same as key)
prefLabel	required	Preferred label of concept
narrower	optional	Array of concepts (URIs) that are narrower concepts of the current concept

Example: http://api.finto.fi/rest/v1/yso/narrowerTransitive?uri=http://www.yso.fi/onto/yso/p19378&lang=en

Parameters:

• uri (mandatory): URI of the concept whose hierarchy to return
• lang (optional): Language of labels. If not given, labels are returned with the default language of the vocabulary.

Returns the hierarchical context of the requested concept. The hierarchy is intended to be used in a hierarchical display and contains the following information:

1. the requested concept
2. the transitive path leading to top-level concepts through skos:broader relationships
3. narrower concepts one level down from all concepts mentioned in items 1 and 2
4. preferred labels of all concepts mentioned in items 1, 2 and 3
5. for leaf concepts (i.e., those mentioned in item 3), a boolean value indicating whether they have narrower concepts

Returns a list of concepts in JSON-LD format. If decoded into RDF, the result is a vocabulary fragment expressed as SKOS.

The returned object contains a broaderTransitive field containing an object having concept URIs as keys and objects with the following fields as values:

Field	Required?	Description
uri	required	URI of concept
prefLabel	required	Preferred label of concept
top	optional	This field is present if the current concept is a toplevel concept in the vocabulary and contains the concept scheme URI
broader	optional	Broader concepts expressed as an array of concept URIs
narrower	optional	Narrower concepts expressed as an array of objects (see below).
notation	optional	Notation of concept

The narrower concepts are expressed as objects with the following fields:

Field	Required?	Description
uri	required	URI of concept
prefLabel	required	Preferred label of concept
hasChildren	required	Boolean value indicating whether the current concept has children (grandchildren of the requested concept)
notation	optional	Notation of concept

Example: http://api.finto.fi/rest/v1/yso/hierarchy?uri=http://www.yso.fi/onto/yso/p19378&lang=en

Parameters:

• uri (mandatory): URI of the concept whose children to return
• lang (optional): Language of labels. If not given, labels are returned with the default language of the vocabulary.

Returns the children of the requested concept. The data is intended to be used in a hierarchical display and contains the following information:

1. the requested concept
2. narrower concepts one level down from the requested concept
3. preferred labels of all concepts mentioned in items 1 and 2
4. for leaf concepts (i.e., those mentioned in item 2), a boolean value indicating whether they have narrower concepts

Returns a list of concepts in JSON-LD format. If decoded into RDF, the result is a vocabulary fragment expressed as SKOS.

The returned object contains a narrower field containing an array of objects with the following fields:

Field	Required?	Description
uri	required	URI of concept
prefLabel	required	Preferred label of concept
hasChildren	required	Boolean value indicating whether the current concept has children (grandchildren of the requested concept)
notation	optional	Notation of concept

Example: http://api.finto.fi/rest/v1/yso/children?uri=http://www.yso.fi/onto/yso/p19378&lang=en

Parameters:

• uri (mandatory): URI of the concept whose related concepts to return
• lang (optional): Language of labels. If not given, labels are returned with the default language of the vocabulary.

Returns the related concepts of the requested concept in JSON-LD format. If decoded into RDF, the result is a vocabulary fragment expressed as SKOS.

The returned object contains a related field containing an array of objects with the following fields:

Field	Required?	Description
uri	required	URI of concept
prefLabel	required	Preferred label of concept

Example: http://api.finto.fi/rest/v1/yso/related?uri=http://www.yso.fi/onto/yso/p19378&lang=en

Parameters:

• lang (optional): Language of labels. If not given, labels are returned in the default language of the vocabulary.

Returns concept groups of the vocabulary in JSON-LD format. If decoded into RDF, the result is a vocabulary fragment expressed as SKOS.

The returned object contains a groups field containing an array of objects with the following fields:

Field	Required?	Description
uri	required	URI of concept group
prefLabel	required	Preferred label of concept group
super	optional	Super group URI(s)
hasMembers	required	Boolean value indicating whether the group has member concepts or if the group is a super group for a another group
notation	optional	Notation of concept

Introduced in Skosmos 1.2.

Parameters:

• uri (mandatory): URI of the concept group whose contents to return
• lang (optional): Language of labels. If not given, labels are returned in the default language of the vocabulary.

Returns the concepts and concept groups that belong to the concept group in JSON-LD format. If decoded into RDF, the result is a vocabulary fragment expressed as SKOS.

The returned object contains a members field containing an array of objects with the following fields:

Field	Required?	Description
uri	required	URI of concept group
prefLabel	required	Preferred label of concept group
isSuper	required	Boolean value indicating whether the group is a supergroup for a another concept group
hasMembers	required	Boolean value indicating whether the group has member concepts or if the group is a super group for a another group
type	required	Type(s) of the resource
notation	optional	Notation of concept

Introduced in Skosmos 1.2.