<img src="https://raw.githubusercontent.com/CLARIAH/grlc/master/src/static/grlc_logo_01.png" width="250px">

grlc, the git repository linked data API constructor, automatically builds Web APIs using shared SPARQL queries. http://grlc.io/

If you use grlc in your work, please cite it as:

@InProceedings{merono2016grlc,
 author = {Mero{\~{n}}o-Pe{\~{n}}uela, Albert and Hoekstra, Rinke},
 title = {{grlc Makes GitHub Taste Like Linked Data APIs}},
 booktitle = {The Semantic Web: ESWC 2016 Satellite Events, Heraklion, Crete, Greece, May 29 -- June 2,  2016},
 year = {2016},
 publisher = {Springer},
 pages = {342--353},
 isbn = {978-3-319-47602-5},
 doi = {10.1007/978-3-319-47602-5_48}
}

What is grlc?

grlc is a lightweight server that takes SPARQL queries (stored in a GitHub or GitLab repository, in your local filesystem, or listed in a URL), and translates them to Linked Data Web APIs. This enables universal access to Linked Data. Users are not required to know SPARQL to query their data, but instead can access a web API.

Quick tutorial

For a quick usage tutorial check out our wiki walkthrough and list of features.

Usage

grlc assumes that you have a collection of SPARQL queries as .rq files (like this). grlc will create one API operation for each SPARQL query/.rq file in the collection.

Your queries can add API parameters to each operation by using the parameter mapping syntax. This allows your query to define query variables which will be mapped to API parameters for your API operation (see here for an example).

Your queries can include special decorators to add extra functionality to your API.

grlc also supports SPARQL queries expressed as json, using the SPARQL Transformer Query in JSON syntax. (Tip: the SPARQL Transformer Playground is very useful when building queries with this syntax).

Query location

grlc can load your query collection from different locations: from a GitHub repository (api-git), from a GitLab repository (api-gitlab), from local storage (api-local), and from a specification file (api-url). Each type of location has specific features and is accessible via different paths. However all location types produce the same beautiful APIs.

From a GitHub repository

API path: http://grlc-server/api-git/<user>/<repo>

grlc can build an API from any Github repository, specified by the GitHub user name of the owner (<user>) and repository name (<repo>).

For example, assuming your queries are stored on a Github repo: https://github.com/CLARIAH/grlc-queries/, point your browser to the following location http://grlc.io/api-git/CLARIAH/grlc-queries/

grlc can make use of git's version control mechanism to generate an API based on a specific version of queries in the repository. This can be done by including the commit sha in the URL path (http://grlc-server/api-git/<user>/<repo>/commit/<sha>), for example: http://grlc.io/api-git/CLARIAH/grlc-queries/commit/79ceef2ee814a12e2ec572ffaa2f8212a22bae23

grlc can also use a subdirectory inside your Github repo. This can be done by including a subdirectory in the URL path (http://grlc-server/api-git/<user>/<repo>/subdir/<subdir>).

From a GitLab repository

API path: http://grlc-server/api-gitlab/<user>/<repo>

grlc can build an API from any GitLab repository, specified by the GitLab user name of the owner (<user>) and repository name (<repo>).

For example, assuming your queries are stored on a GitLab repo: https://gitlab.com/c-martinez/grlc-queries, point your browser to the following location http://grlc.io/api-gitlab/c-martinez/grlc-queries/

grlc can make use of git's version control mechanism to generate an API based on a specific version of queries in the repository. This can be done by including the name of a branch in the URL path (http://grlc-server/api-gitlab/<user>/<repo>/branch/<branch>), for example: http://grlc.io/api-gitlab/c-martinez/grlc-queries/branch/master

grlc can also use a subdirectory inside your GitLab repo. This can be done by including a subdirectory in the URL path (http://grlc-server/api-gitlab/<user>/<repo>/subdir/<subdir>), for example: http://grlc-server/api-gitlab/c-martinez/grlc-queries/subdir/subdir.

From local storage

API path: http://grlc-server/api-local/

grlc can generate an API from a local directory in the computer where your grlc server runs. You can configure the location of this directory in your grlc server configuration file. See also how to install and run your own grlc instance.

When the API is generated from a local directory, API information can be loaded from a configuration file in that folder. This file must be called local-api-config.ini and it has the following format:

[repo_info]
repo_title = Some title
api_description = Description of my API
contact_name = My name
contact_url = https://mypage/
licence_url = https://mylicence/

From a specification file

API path: http://grlc-server/api-url/?specUrl=<specUrl>

grlc can generate an API from a yaml specification file accessible on the web.

For example, assuming your queries are listed on spec file: https://raw.githubusercontent.com/CLARIAH/grlc-queries/master/urls.yml, point your browser to the following location http://grlc.io/api-url?specUrl=https://raw.githubusercontent.com/CLARIAH/grlc-queries/master/urls.yml

Specification file syntax

A grlc API specification file is a YAML file which includes the necessary information to create a grlc API, most importantly a list of URLs to decorated and HTTP-dereferenceable SPARQL queries. This file should contain the following fields

title: Title of my API
description: API description
contact: Contact details of the API owner. This should include the name and url properties.
licence: A URL pointing to the licence file for the API.
queries: A list of URLs of SPARQL queries (with header decorators). Alternatively a query can be defined as a dictionary with a name and a url.

For example:

title: Title of my API
description: Description of my API
contact:
  name: Contact Name
  url: https://www.mywebsite.org
licence: http://example.org/licence.html
queries:
  - https://www.mywebsite.org/query1.rq
  - https://www.mywebsite.org/query2.rq
  - https://www.otherwebsite.org/query3.rq
  - name: QueryFour
    url: https://www.mywebsite.org/query4.rq

grlc generated API

The API paths of all location types point to the generated swagger-ui style API documentation. On the API documentation page, you can explore available API calls and execute individual API calls.

You can also view the swagger spec of your API, by visiting <API-path>/swagger, for example: http://grlc.io/api-git/CLARIAH/grlc-queries/swagger

grlc query execution

When you call an API endpoint, grlc executes the SPARQL query for that endpoint by combining supplied parameters and decorators.

There are 4 options to specify your own endpoint:

Add a sparql_endpoint on your config.ini
Add a endpoint parameter to your request: 'http://grlc.io/user/repo/query?endpoint=http://sparql-endpoint/'. You can add a #+ endpoint_in_url: False decorator if you DO NOT want to see the endpoint parameter in the swagger-ui of your API.
Add the #+ endpoint: decorator.
Add the URL of the endpoint on a single line in an endpoint.txt file within the GitHub repository that contains the queries.

The endpoint call will return the result of executing the query as a json representation of rdflib.query.QueryResult (for other result formats, you can use content negotiation via HTTP Accept headers). For json responses, the schema of the response can be modified by using the #+ transform: decorator.

Decorator syntax

Special decorators are available to make your swagger-ui look nicer and to increase functionality. These are provided as comments at the start of your query file, making it still syntactically valid SPARQL. All decorators start with #+ , for example:

#+ decorator_1: decorator value
#+ decorator_1: decorator value

SELECT * WHERE {
  ?s ?p ?o .
}

The following is a list of available decorators and their function:

`summary`

Creates a summary of your query/operation. This is shown next to your operation name in the swagger-ui.

Syntax:

#+ summary: This is the summary of my query/operation

Example query and the equivalent API operation.

`description`

Creates a description of your

Grlc

Install / Use

README