Linked Data API

Introduction

Vocabularies published through RVA's SISSVoc instance are made available through a selection of linked data endpoints.

The rationale for these endpoints is provided in this paper:

Simon J D Cox, Jonathan Yu and Terry Rankine, SISSVoc: A Linked Data API for access to SKOS vocabularies, Semantic Web Journal, volume 7, number 1, 2016. Available at: http://www.semantic-web-journal.net/system/files/swj880.pdf.

SISSVoc works with SKOS vocabularies. For example, the /concept endpoint produces a list of SKOS Concepts (instances of the skos:Concept type). If you use these endpoints to access a non-SKOS vocabulary that has been published through SISSVoc, most likely there will be no results; only the /resource?uri={IRI} and the other generic resource endpoints will return anything of interest.

Working with JavaScript-based services

Cross-Origin Resource Sharing (http://enable-cors.org/) is enabled for linked data endpoints served from vocabs.ardc.edu.au. This means that endpoint URLs can be used by JavaScript code in your own web applications.

Endpoint templates

The following table lists the templates for the endpoints supported by each published vocabulary. The notes below the table show how to instantiate a template, and the following section shows how to incorporate the result into a complete URL.

Notes:

• An endpoint template of type “List” returns a list of zero or more items. An endpoint template of type “Item” returns at most one item.

• Where a template includes a component in italics, that component, including surrounding braces, is to be replaced by specific content.

  • Where the component is  {text} , the component needs to be encoded using percent encoding (https://en.wikipedia.org/wiki/Percent-encoding) as part of the URL: for example, a space must be encoded as %20.

• For historical reasons, the endpoint templates use ?uri= instead of the more correct ?iri=.

• The default format of the result is HTML. Other formats may be specified by including a “suffix” component in the URL. If the endpoint template includes a question mark, the suffix is placed before the question mark. For example, /concept/narrower.json?uri={baseConcept} will return data in JSON format.

  • Supported format suffixes are: .html, .json, .rdf (returns RDF/XML), .text (returns JSON, but with a text MIME type), .ttl, and .xml (returns XML in the Elda library's own schema).

• SISSVoc is based on the Elda library (https://github.com/epimorphics/elda), which implements the Linked Data API (https://github.com/UKGovLD/linked-data-api/blob/wiki/Specification.md). Therefore, URLs can make use of the other features provided by the Elda library.

Constructing a URL

URLs that access the linked data endpoints are constructed from the following components in sequence. (The value in the Example column for vocabulary identifier is artificially chosen; it does not correspond to a vocabulary published at RVA.)

Combining the values in the example column yields: http://vocabs.ardc.edu.au/repository/api/lda/ands/nal-agricultural-thesaurus/nal-thesaurus-2015-edition/concept  (Again, please note that this URL is a sample only, and does not resolve.)

Notes:

1. The components of the vocabulary identifier are turned into “slugs” (https://en.wikipedia.org/wiki/Semantic_URL#Slug) before inclusion in the URL. In practice, this means conversion to lower case, and the replacement of all non-alphanumeric data with hyphens.  You do not have to guess what a slug will be ; each vocabulary available through SISSVoc on RVA has, on its view page, a sample link to a SISSVoc endpoint.

2. There are a small number of vocabularies that are specially “curated” by ARDC, because they are of particular importance for the working of ARDC services (including RVA). For some of those curated vocabularies, the vocabulary identifier section for the current version of the vocabulary does not include the vocabulary owner and version title. The vocabularies in this category are: anzsrc-2020-for, anzsrc-2020-seo, anzsrc-for, anzsrc-seo, and gcmd-sci. As an example, the /concept endpoint for the anzsrc-for vocabulary is accessible at http://vocabs.ardc.edu.au/repository/api/lda/anzsrc-for/concept.

Special URLs for current versions

RVA supports the publication of multiple versions of a vocabulary; access to the linked data endpoints of the different versions is effected by using the different version titles in the vocabulary identifier components of the URL, as shown in the previous section. However, for published (i.e., not marked as "deprecated") vocabularies there is an additional “shortcut” provided to access the endpoints of the version which has been tagged as the “current” version in the portal. In addition to the endpoints available with the version title, the same endpoints are also available automatically with current as the version title. For example, if the version with version slug nal-thesaurus-2015-edition is tagged as the current version, the following two URLs would generate the same page:

• http://vocabs.ardc.edu.au/repository/api/lda/ands/nal-agricultural-thesaurus/nal-thesaurus-2015-edition/concept

• http://vocabs.ardc.edu.au/repository/api/lda/ands/nal-agricultural-thesaurus/current/concept

Please note the exception described in Note 2 of the previous section, that applies to “curated” vocabularies. Access to the current version of those vocabularies is obtained without the use of any version slug.