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

Author: Albert Meroño
Copyright: Albert Meroño, VU University Amsterdam
License: MIT License (see license.txt)

Install and run

git clone https://github.com/CLARIAH/grlc
cd grlc
virtualenv .
source bin/activate
pip install -r requirements.txt
python src/server.py

Direct your browser to http://localhost:8088.

Alternatively, you can use the provided Gunicorn configuration to run it as a daemon on your server.

Docker

A bundle containing grlc, nginx and other dependencies is available at https://hub.docker.com/. If you have a working installation of docker and docker-compose, you can quickly deploy grlc in your system:

• docker pull clariah/grlc:1.0.0: install the container
• docker-compose up: launch grlc
• docker-compose up /bin/bash: get into container

Usage

grlc assumes a GitHub repository (support for general git repos is on the way) where you store your SPARQL queries as .rq files (like in this one). grlc will create an API operation per such a SPARQL query/.rq file.

If you're seeing this, your grlc instance is up and running, and ready to build APIs. Assuming you got it running at http://localhost:8088/ and your queries are at https://github.com/CEDAR-project/Queries, just point your browser to the following locations:

• To request the swagger spec of your API, http://localhost:8088/api/username/repo/spec, e.g. http://localhost:8088/api/CEDAR-project/Queries/spec or http://localhost:8088/api/CLARIAH/wp4-queries/spec
• To request the api-docs of your API swagger-ui style, http://localhost:8088/api/username/repo/api-docs, e.g. http://localhost:8088/api/CEDAR-project/Queries/api-docs or http://localhost:8088/api/CLARIAH/wp4-queries/api-docs

By default grlc will direct your queries to the DBPedia SPARQL endpoint. To change this either:

• Add a endpoint: decorator in the first comment block of the query text (preferred, see below)
• Add the URL of the endpoint on a single line in an endpoint.txt file within the GitHub repository that contains the queries.
• Or you can directly modify the grlc source code (but it's nicer if the queries are self-contained)

That's it!

Decorator syntax

A couple of SPARQL comment embedded decorators are available to make your swagger-ui look nicer (note all comments start with #+ ):

• To specify a query-specific endpoint, #+ endpoint: http://example.com/sparql.

• To indicate the HTTP request method, #+ method: GET.

• To paginate the results in e.g. groups of 100, #+ pagination: 100.

• To create a summary of your query/operation, #+ summary: This is the summary of my query/operation

• To assign tags to your query/operation,

  #+ tags:
  #+   - firstTag
  #+   - secondTag

• To indicate which parameters of your query/operation should get enumerations (and get dropdown menus in the swagger-ui),

  #+ enumerate:
  #+   - var1
  #+   - var2

  Notice that these should be plain variable names without SPARQL/BASIL conventions (so var1 instead of ?_var1_iri)

See examples at https://github.com/CEDAR-project/Queries.

Features

• Request parameter mappings into SPARQL: grlc is compliant with BASIL's convention on how to map GET/POST request parameters into SPARQL
• Automatic, user customizable population of parameter values in swagger-ui's dropdown menus via SPARQL triple pattern querying
• URL-based content negotiation: you can request for specific content types by attaching them to the operation request URL, e.g. http://localhost:8088/CEDAR-project/Queries/residenceStatus_all.csv will request for results in CSV
• Pagination of API results, as per the pagination decorator and GitHub's API Pagination Traversal