REST API
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:
- 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 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:
- 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). |
| 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:
- 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) |
| 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.