API v1

The sections that follow can be experienced interactively via the swagger page for v1. That swagger page is also the reference documentation for the API.

Please be aware that due to the swagger implementation, rendering a lengthy result in your browser may take a very long time (minutes!). When calling the API from an application, keep in mind that all URL-provided parameters have to be URL encoded, as can be seen in the Request URL field after execution of an example call.

The GraphQL-LD endpoint

The endpoint /graphqlld is a versatile endpoint, providing full query access to the SKOS data.

Users need to understand the basics of the GraphQL query language and how it can be used to query linked data, with these details on queries you can write. The Comunica framework is used in this platform to provide this functionality.

Knowledge of JSON-LD is helpful, but not explicitly required, because the user does not need to provide a JSON-LD context; we're using a built-in context, covering the entire vocabulary used in our SKOS data.

A first input to this endpoint, query, is the GrapQL-LD query: a string. This is an example query, requesting information about a specific concept:

{
  TYPE(_:Concept)
  id(_:ID) @single
  prefLabel @single
  altLabel @optional
  definition @single @optional
}

In this example, ID is a parameter. Its value must be supplied in the second input of this endpoint, parameters, a simple JSON key-value structure. For the example, this JSON would do (we provide one of the available URIs that identify a specific concept):

{
  "ID": "http://ilearn.ilabt.imec.be/vocab/curr1/s-industrieel-onderhoud-en-ontwerp"
}

The endpoint returns a JSON-LD structure.

• The "@context" entry expresses general statements, that apply to all corresponding elements in the @graph entry below it, and gives the properties their semantic meaning. In fact, this returned context is our built-in context described above.
• The "@graph" entry contains the effective information, as if it were plain JSON: easy to consume by a program and yet human readable and structured as requested in the input's GrapQL-LD query.

This way, we return information in a popular format, while keeping the semantic information in the payload.

Please note that, when trying out this endpoint using the swagger page, the example query and parameters are shown as a single line each, while the actual contents can contain newlines (as shown above). This is a limitation of the swagger presentation. When experimenting, these lines can be copied, formatted, modified and pasted back in those fields (including formatting).

The specific endpoints

These endpoints are in fact easy to use specialisations of what can be done using the GraphQL-LD endpoint. Possible users, not yet familiar with GraphQL-LD, can use them to quickly retrieve some typical information form the SKOS data.

The endpoints all return a JSON-LD structure, as described above for the GraphQL-LD endpoint.

The following endpoints provide resource-alike information.

• /collections: gives the list of collections (their URIs and labels)
• /collections/{collection}: detailed information about one collection (labels and members, with URI and labels). Note that {collection} stands for "URL encoded URI of the collection".
• /concepts: gives the list of concepts (their URIs and labels)
• /concepts/{concept}: detailed information about one concept (labels, connected concepts, collections the concept is a member of, all with URI and labels). Note that {concept} stands for "URL encoded URI of the concept".

The following endpoints provide overview-alike information.

• /overview/sleutelcompetenties: gives the list of sleutelcompetenties (if they're top concepts) and their subordinate concepts (all with URI and labels)
• /overview/leergebieden: gives the list of leergebieden (if they're top concepts) and their subordinate concepts (all with URI and labels)
• /overview/onderwijsstructuur: gives the list of onderwijsstructuur (if they're top concepts) and their subordinate concepts (all with URI and labels)
• /overview/trefwoorden: gives the list of trefwoorden and their related concepts (all with URI and labels)
• /overview/vakken: gives the list of vakken and their related concepts (all with URI and labels)
• /overview/onderwijsdoelen: gives the list of onderwijsdoelen and their related concepts(all with URI and labels)

The example endpoints

Available in v1 only

The endpoints that demonstrate example usage are not interesting in what they return as such, because these contents are based on example data, hardcoded in the demo code. They are interesting when having their implementation code at hand, to see how this code calls the endpoints described above.

Example endpoint /apps

This example starts from a (here hardcoded) set of "applications", all classified by means of one or more URIs of concepts in our metadata.

The intention of this endpoint is to see which of the known "applications" pass the filter that can be applied.

What the endpoint returns: a plain JSON structure, with contents depending on the parameters provided:

• Parameter filter is not used: the entire set of "applications"
• Parameter filter = a concept URI; parameter connections is not used: the subset of all "applications" classified with that concept URI
• Parameter filter = a concept URI; parameter connections = a comma separated list of the proposed types of connection: the subset of all "applications" classified with that concept URI or with any of the concept URIs connected to that concept by means of any of the given types of connection.