Append Data to the URL Query for SPARQL Requests With Curl

Although this post uses Dydra graph database cloud service to illustrate the concepts, the approach is equally applicable to any RDF graph store that supports the SPARQL 1.1 Protocol and SPARQL 1.1 Graph Store HTTP Protocol

Following a short conversation on Twitter, the awesome Daniel Stenberg kindly implemented a new --url-query option in curl. This option is available in the curl 7.87.0 release. Daniel has blogged more about this new option, but here I want to demonstrate how it can make life easier for SPARQL 1.1 Protocol and SPARQL 1.1 Graph Store HTTP Protocol requests.

I’ve written previously about managing data in Dydra with SPARQL 1.1 Graph Store HTTP Protocol, so I’ll build on those examples in this post.

Authenticating requests to Dydra

Rather than passing your API key using the ?auth_token query string parameter, it is preferable to use either the -u/--user or --oauth2-bearer options. This can help avoid your credentials being inadvertently logged if your application logs request URLs.

Examples using curl to append data to the URL query with SPARQL 1.1 Graph Store HTTP Protocol

Get the named graph http://example.com/mygraph in the nlv01111/gsp repository in JSON-LD format

Previously it would be necessary to either URL-encode the graph IRI when constructing the request URL, or use the -G/--get and --data-urlencode options to make curl do a GET request with URL-encoded query string parameters:

curl "https://dydra.com/nlv01111/gsp/service" \
  --header "Accept: application/ld+json" \
  --data-urlencode "graph=http://example.com/mygraph" \
  -G

With the new --url-query option, we can omit the -G option:

curl "https://dydra.com/nlv01111/gsp/service" \
  --header "Accept: application/ld+json" \
  --url-query "graph=http://example.com/mygraph"

Put a local RDF/XML file data.rdf to the named graph http://example.com/mygraph in the nlv01111/gsp repository:

Previously we had no way to use curl to URL encode the query string parameters for anything other than GET requests. Life is now easier with --url-query:

curl -X PUT "https://dydra.com/nlv01111/gsp/service" \
  --data-binary @data.rdf \
  --header "Content-Type: application/rdf+xml" \
  --url-query "graph=http://example.com/mygraph" \
  --oauth2-bearer $MY_API_KEY

Examples using curl to append data to the URL query with SPARQL 1.1 Protocol

SPARQL query via GET

We can use --url-query to URL encode the query using the GET method:

curl "https://dydra.com/nlv01111/gsp/sparql" \
  --header "Accept: application/sparql-results+json" \
  --url-query "query=select * where { ?s ?p ?o }"

Additionally we can specify the RDF Dataset for a query via the default-graph-uri and named-graph-uri parameters:

curl "https://dydra.com/nlv01111/gsp/sparql" \
  --header "Accept: application/sparql-results+json" \
  --url-query "query=select * where { ?s ?p ?o }" \
  --url-query "default-graph-uri=http://example.com/mygraph"

We can also specify multiple graph IRIs:

curl "https://dydra.com/nlv01111/gsp/sparql" \
  --header "Accept: application/sparql-results+json" \
  --url-query "query=select * where { ?s ?p ?o }" \
  --url-query "default-graph-uri=http://example.com/mygraph" \
  --url-query "default-graph-uri=http://example.com/mygraph2"

SPARQL query via POST directly

Where the query text is longer, we may prefer to use the POST method and include the query directly and unencoded as the HTTP request message body:

curl -X POST "https://dydra.com/nlv01111/gsp/sparql" \
  --header "Accept: application/sparql-results+json" \
  --header "Content-Type: application/sparql-query" \
  --data-binary @query.rq

Additionally we can use --url-query to specify the RDF Dataset for a query via the default-graph-uri and named-graph-uri parameters:

curl -X POST "https://dydra.com/nlv01111/gsp/sparql" \
  --header "Accept: application/sparql-results+json" \
  --header "Content-Type: application/sparql-query" \
  --data-binary @query.rq \
  --url-query "default-graph-uri=http://example.com/mygraph"

SPARQL update via POST directly

For updates, we must use the POST method. Here we include the update directly and unencoded as the HTTP request message body:

curl -X POST "https://dydra.com/nlv01111/gsp/sparql" \
  --header "Content-Type: application/sparql-update" \
  --data-binary @update.ru \
  --oauth2-bearer $MY_API_KEY

Additionally we can use --url-query to specify the RDF Dataset for a update via the using-graph-uri or using-named-graph-uri parameters:

curl -X POST "https://dydra.com/nlv01111/gsp/sparql" \
  --header "Content-Type: application/sparql-update" \
  --data-binary @update.ru \
  --url-query "using-graph-uri=http://example.com/mygraph" \
  --oauth2-bearer $MY_API_KEY