REST API

Introduction

This document specifies the REST API (v1) in Skosmos v0.4+ 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.

Basics

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, as of 2014-07-08 running Skosmos 0.4)

REST URLs begin with /rest/v1.

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

Data format

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.

CORS support

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

JSONP callbacks

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.

Global methods

/vocabularies

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

/search

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'
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)

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 [RESTv1#//search 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

/data

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.

Vocabulary-specific methods

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

/`<vocid>`/

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/

/`<vocid>`/types

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

/`<vocid>`/topConcepts

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

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

/`<vocid>`/data

Parameters:

format (optional): the MIME type of the serialization format, e.g. "text/turtle" or "application/rdf+xml" NOT IMPLEMENTED

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.

Note: The current implementation redirects to an external URL which serves the actual RDF data. The format is whatever the download URL serves (in practice, usually Turtle).

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

/`<vocid>`/search

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
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.

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

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

/`<vocid>`/lookup

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:

exact match on preferred label
case-insensitive match on preferred label
exact match on alternate label
case-insensitive match on alternate label
exact match on hidden label NOT IMPLEMENTED
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 [RESTv1#//search 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

/`<vocid>`/vocabularyStatistics

Returns the amount of skos:Concepts in the vocabulary.

The returned object contains the following fields:

Field	Required?	Description
id	required	identifier of vocabulary
title	required	title of the vocabulary
concepts	required	count of concepts in the vocabulary

Introduced in Skosmos 0.7.

/`<vocid>`/labelStatistics

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

Introduced in Skosmos 0.7.

Concept-specific methods

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).

/`<vocid>`/label

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

/`<vocid>`/data

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

/`<vocid>`/broader

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

/`<vocid>`/broaderTransitive

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

/`<vocid>`/narrower

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

/`<vocid>`/narrowerTransitive

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

/`<vocid>`/hierarchy

Parameters:

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

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

the requested concept
the transitive path leading to top-level concepts through skos:broader relationships
narrower concepts one level down from all concepts mentioned in items 1 and 2
preferred labels of all concepts mentioned in items 1, 2 and 3
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).

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)

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

/`<vocid>`/children

Parameters:

uri (mandatory): URI of the concept whose children to return
lang (optional): Language of labels. If not given, labels in all languages are returned.

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

the requested concept
narrower concepts one level down from the requested concept
preferred labels of all concepts mentioned in items 1 and 2
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)

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

/`<vocid>`/related

Parameters:

uri (mandatory): URI of the concept whose related concepts to return
lang (optional): Language of labels. If not given, labels in all languages are returned.

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

REST API

Introduction

Basics

Data format

CORS support

JSONP callbacks

Global methods

/vocabularies

/search

/data

Vocabulary-specific methods

/<vocid>/

/<vocid>/types

/<vocid>/topConcepts

/<vocid>/data

/<vocid>/search

/<vocid>/lookup

/<vocid>/vocabularyStatistics

/<vocid>/labelStatistics

Concept-specific methods

/<vocid>/label

/<vocid>/data

/<vocid>/broader

/<vocid>/broaderTransitive

/<vocid>/narrower

/<vocid>/narrowerTransitive

/<vocid>/hierarchy

/<vocid>/children

/<vocid>/related

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

/`<vocid>`/

/`<vocid>`/types

/`<vocid>`/topConcepts

/`<vocid>`/data

/`<vocid>`/search

/`<vocid>`/lookup

/`<vocid>`/vocabularyStatistics

/`<vocid>`/labelStatistics

/`<vocid>`/label

/`<vocid>`/data

/`<vocid>`/broader

/`<vocid>`/broaderTransitive

/`<vocid>`/narrower

/`<vocid>`/narrowerTransitive

/`<vocid>`/hierarchy

/`<vocid>`/children

/`<vocid>`/related