REST API

Osma Suominen edited this page Jun 20, 2016 · 36 revisions

This information has moved!

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.


Introduction

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.

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.

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

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

/types

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

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

/<vocid>/data

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

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

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

  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

/<vocid>/vocabularyStatistics

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.

/<vocid>/labelStatistics

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.

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

/<vocid>/children

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

/<vocid>/related

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

/<vocid>/groups

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.

/<vocid>/groupMembers

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.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.