README.md

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

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

Install and run

git clone --recursive https://github.com/CLARIAH/grlc
cd grlc
virtualenv .
source bin/activate
pip install -r requirements.txt
python grlc.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.

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

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

Request parameter mappings into SPARQL

grlc is compliant with BASIL's convention on how to map GET/POST request parameters into SPARQL.