Quick tutorial

This tutorial is a quick walkthrough for deploying your own Linked Data API using grlc. Since we'll be using grlc's public instance, you don't need to install anything; a GitHub account will do (although sharing queries on GitHub is not mandatory, it's the easiest way to get SPARQL-based APIs quickly up and running). Having your own SPARQL endpoint is optional.

This is the magic recipe (click on the links for further detail):

1. Log into GitHub / create GitHub account
2. Create a repository for queries
3. Put your queries up in your repository
4. Endpoints
5. Create your Linked Data API
6. Using your Linked Data API
7. Describing your queries further
8. Further steps

If after following this steps you don't manage to have a working API, please let us know on gitter

Log into GitHub / create GitHub account

The first thing we'll need is to log into GitHub. If you don't have a GitHub account, you'll be prompted to create one. Just follow the on-screen instructions.

Create a repository for queries

Once you're logged in, you'll see a dashboard screen similar to this one:

To create a new repository, click on the + sign in the top right corner of the screen, and then click on New repository.

Fill in the form to give your repository a name, and (optionally) a description. You can keep the rest of the defaults. Make sure the visibility is set to Public (grlc will need this to access the queries we'll store in the repo). When done, click on Create repository.

The URI of your repository will look something like https://github.com/username/repo. In my case that's https://github.com/albertmeronyo/my-linked-data-api. We'll use this URI later to let grlc know where to find the queries of our API.

Put your queries up in your repository

Next, we need to create one file inside our new repository for each query we want to transform into an API method. In order to do this, let's first get our query written in SPARQL (grlc supports much more than just SPARQL; but let's use it as a prototypical Linked Data example). We'll type a SPARQL query that retrieves the names of all the Hard Rock bands DBpedia knows about, like this:

PREFIX dbo: <http://dbpedia.org/ontology/>
PREFIX dbr: <http://dbpedia.org/resource/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>

SELECT ?band_label { 
    ?band rdf:type dbo:Band ;
          dbo:genre dbr:Hard_Rock ;
          rdfs:label ?band_label .
} ORDER BY ?band_label

You can try out this query at the DBpedia SPARQL endpoint, or with the assistance of the handy YASGUI editor (I've typed it there for you). It's really important for grlc to not forget any prefixes, so double check you've declared all prefixes used in your queries.

Once you're sure the query returns results, we'll put it up on your GitHub repo. To do this, click on Create new file in the repository page.

After this, you'll see the file editor. Give your file a name first; it's improtant you end up with .rq or .sparql, so grlc knows its contents is actually a SPARQL query.

Now, go back up where you've tested our Hard Rock bands query (or just scroll up this page), select all the text of this query, from PREFIX dbo: until ?band_label, and copy-paste it into the query editor as shown below.

Endpoints

Before we finish, we need to tell grlc the endpoint URI against which the query should be executed. There is a number of ways of doing this: you can specify the endpoint URI in the query file, in the repo (in case all queries execute against the same endpoint), or alternatively at execution time as a parameter. To keep things simple, and since we're still editing our query, we'll add the endpoint URI in the query file. We do this by adding the following line at the top:

#+ endpoint: http://dbpedia.org/sparql

(If your endpoint is different from DBpedia's you just type your endpoint's URI instead). So our query editor should now look like this:

Notice that the endpoint metadata (as well as all other metadata fields used by grlc) is indicated through standard SPARQL comments plus a bit of YAML syntax. This makes sure that the content of SPARQL files is always SPARQL compliant and doesn't break any standard.

After this, scroll all the way down until you see a Commit new file button, and click on it (optionally, you can add a description to the commit):

That's it! This puts our new query up on GitHub, making it available for deference to any client. To double check, you can see that now your repository contains your recently created SPARQL file, and a README.md file (if you chose to have a default one when you created the repository):

Create your Linked Data API

Using your Linked Data API

Describing your queries further

Further steps