GRLC.io, setup a conveniance API on a SPARQL endpoint

Author

Paul van Genuchten

A challenge with pure SKOS RDF codelists is that they are hard to consume by tools unaware of semantic web conventions. Various tools exist which enable to browse through a skos codelist, such as skosmos and vocprez. This recipe introduces a more generic approach to setup a conveniance API on top of a SPARQL endpoint, which can also be used for codelists.

The GRLC software creates an OpenAPI facade on any SPARQL endpoint. Users send an OpenAPI request to GRLC, GRLC translates the request to a SPARQL query and forwards it to the SPARQL endpoint, the result of the SPARQL query is returned to the user as json or html.

For this recipe you need to have an account on github, login and create a new public repository. This repository will contain the configuration of our new service. At creation, select a MIT or CC-0 license (or add a LICENSE file manually).

Either clone the repository and work locally or use the webbased Github text editor to create and modify files.

Create a new file named endpoint.txt, which contains the SPARQL endpoint we’re going to use for this recipe.

https://virtuoso.isric.org/sparql

Create a new file named urls.yml, wich contains the configuration of our new service.

title: My GRLC experiment
description: a conveniance API to browse soil codelists
contact:
  name: My name
  url: https://example.com
licence: https://github.com/{github-handle}/{github-project}/blob/main/LICENSE

We’re now ready to set up the endpoints of our service. Each endpoint is defined by a SPARQL query, stored as a .rq file. Create a file carbonOrganicProcedure.rq.

PREFIX skos:<http://www.w3.org/2004/02/skos/core#>

SELECT DISTINCT ?term ?concept ?definition WHERE  {
     ?concept skos:prefLabel ?term .
     ?concept skos:inScheme ?conceptScheme .
     FILTER(regex(str(?conceptScheme),'carbonOrganicProcedure'))
     ?concept skos:definition ?definition.
}
ORDER BY ?term

This query will select all concepts in scheme carbonOrganicProcedure.

Now navigate your browser to https://grlc.io/api/{github-handle}/{github-project} (replace {gh} with your setup) and notice that GRLC has set up an OpenAPI service for your configuration. Click the method in blue, Try it out and Execute to see the service in action.

Try to set up more endpoints by creating new .rq files with alternative SPARQL queries (try the query first at https://virtuoso.isric.org/sparql).

Also have a look at the GRLC documentation to evaluate decorators you can add to your queries to facilitate pagination, tagging, defaults etc.

GRLC.io is a service provided by the authors. You can set up your own instance of GRLC with the GRLC docker image.

Read more

GRLC