-
Notifications
You must be signed in to change notification settings - Fork 5
cURL tutorial
BASIL is a system based on a Web API for creating and managing a stack of Web APIs on top SPARQL endpoints. On its own, BASIL does not come with a graphic user interface (the project Pesto provides a GUI for BASIL).
Here is an description of the commands you can perform with cURL (sometimes examples are taken from http://basil.kmi.open.ac.uk).
$ curl http://basil.kmi.open.ac.uk/basil
Output:
[{"id":"1ievifouaafs6","modified":1480611898000,"name":"List of publications by the CORE team from ORO","createdBy":"mcancellieri","location":"http://basil.kmi.open.ac.uk/basil/1ievifouaafs6"},{"id":"sksbahd9ynoh","modified":1480607179000,"name":"List of publications by Enrico and Matteo from ORO","createdBy":"enridaga","location":"http://basil.kmi.open.ac.uk/basil/sksbahd9ynoh"}, ...]
Prepare a user specification as json file, as follows
{"username":"penelope","password":"mypassword","password2":"mypassword","email":"example@example.org"}
and call make the call to the related endpoint:
$ curl -v -X POST http://localhost:8080/basil/users -d @user.json --header "Content-Type: application/json"
APIs created by the user can be accessed by:
curl http://localhost:8080/basil/users/<username>/apis
Prepare a API specification as SPARQL query, as follows:
$ echo "PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
> PREFIX dct: <http://purl.org/dc/terms/>
>
> select distinct ?Concept ?Type where {
> {?_entity_iri dct:subject* ?Concept . bind ("C" as ?Type) }
> UNION
> {?_entity_iri rdf:type* ?Concept . bind ("T" as ?Type) }
> }">query.sparql
This query is supposed to be executed towards the DBPedia SPARQL endpoint. Create and API in the following way:
$ curl -u penelope:mypassword -X PUT "http://localhost:8080/basil" -H "X-Basil-Endpoint: http://dbpedia.org/sparql" -T query.sparql
Reply should be an HTTP 201 response with the following content:
{"message":"Created","location":"http://localhost:8080/basil/s50nwb9679dd"}
All endpoints are listed in a set of X-Basil-* headers, listed on top of any response. The root of the api endpoint is by default redirected to the /spec endpoint:
$ curl -v http://localhost:8080/basil/s50nwb9679dd
* Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8080 (#0)
> GET /basil/s50nwb9679dd HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.52.1
> Accept: */*
>
< HTTP/1.1 303 See Other
< Date: Fri, 24 Mar 2017 17:48:11 GMT
< X-Basil-Api: http://localhost:8080/basil/s50nwb9679dd/api
< X-Basil-Spec: http://localhost:8080/basil/s50nwb9679dd/spec
< X-Basil-Direct: http://localhost:8080/basil/s50nwb9679dd/direct
< X-Basil-View: http://localhost:8080/basil/s50nwb9679dd/view
< X-Basil-Docs: http://localhost:8080/basil/s50nwb9679dd/docs
< X-Basil-Swagger: http://localhost:8080/basil/s50nwb9679dd/api-docs
< Location: http://localhost:8080/basil/s50nwb9679dd/spec
< Content-Length: 0
< Server: Jetty(9.3.z-SNAPSHOT)
<
* Curl_http_done: called premature == 0
* Connection #0 to host localhost left intact
Each one of the endpoints can be used to access/create/modify API features using HTTP methods: PUT (create), POST (replace), GET (read), DELETE (remove) in a classic REST-style way.
GET: Used to access the API. Following the example above, a simple call would return an error:
$ curl http://localhost:8080/basil/s50nwb9679dd/api
{"error":"Missing mandatory query parameters: entity\t\n"}
A correct call would be instead:
$ curl http://localhost:8080/basil/s50nwb9679dd/api?entity="http://dbpedia.org/resource/Rome"
----------------------------------------------------------------------------------------------------
| Concept | Type |
====================================================================================================
| <http://dbpedia.org/resource/Rome> | "C" |
| <http://dbpedia.org/resource/Category:World_Heritage_Sites_in_Italy> | "C" |
| <http://dbpedia.org/resource/Category:Rome> | "C" |
| <http://dbpedia.org/resource/Category:Populated_places_established_in_the_8th_century_BC> | "C" |
| <http://dbpedia.org/resource/Category:New_Testament_cities> | "C" |
[...]
Alternatives are:
$ curl http://localhost:8080/basil/s50nwb9679dd/api.json?entity="http://dbpedia.org/resource/Rome"
$ curl http://localhost:8080/basil/s50nwb9679dd/api.xml?entity="http://dbpedia.org/resource/Rome"
$ curl http://localhost:8080/basil/s50nwb9679dd/api.csv?entity="http://dbpedia.org/resource/Rome"
It is also possible to DELETE an API (and all its sub-resources):
$ curl -v -u penelope:mypassword -X DELETE "http://localhost:8080/basil/s50nwb9679dd"
View with GET:
$ curl "http://localhost:8080/basil/s50nwb9679dd/spec"
Modify with PUT:
$ curl -v -u penelope:mypassword -X PUT "http://localhost:8080/basil/s50nwb9679dd/spec" -H "X-Basil-Endpoint: http://dbpedia.org/sparql" -T query.sparql
See and manage Views.
For instance, the following Mustache view can be used to format the lists of concepts obtained from DBPedia in the previous examples. The template would look as follows:
<ul>
{{#items}}
<li><a href="{{Concept}}">{{Concept}}</a> (<small>{{Type}}</small>)</li>
{{/items}}
</ul>
Assuming the template to be in file list.tmpl, the command would look as follows:
$ curl -u penelope:mypassword -X PUT "http://localhost:8080/basil/s50nwb9679dd/view/list?type=text/html" -H "Content-type: template/mustache" -T list.tmpl
The type parameters tells the BASIL view engine what is supposed to be the output format of the view, while the Content-Type header how to process the template. You can update a view in the same way.
To call the API using the view to process the output, use the view name as extension of the api resource, as follows:
$ curl http://localhost:8080/basil/s50nwb9679dd/api.list?entity=http://dbpedia.org/resource/Rome
<ul>
<li><a href="http://dbpedia.org/resource/Rome">http://dbpedia.org/resource/Rome</a> (<small>C</small>)</li>
<li><a href="http://dbpedia.org/resource/Category:World_Heritage_Sites_in_Italy">http://dbpedia.org/resource/Category:World_Heritage_Sites_in_Italy</a> (<small>C</small>)</li>
<li><a href="http://dbpedia.org/resource/Category:Rome">http://dbpedia.org/resource/Category:Rome</a> (<small>C</small>)</li>
[...]
This is as easy as:
$ curl http://localhost:8080/basil/s50nwb9679dd/view
[{"id":"list","extension":"list","content-type":"template/mustache","type":"text/html","template":"<ul>\n{{#items}}\n <li><a href=\"{{Concept}}\">{{Concept}}</a> (<small>{{Type}}</small>)</li>\n{{/items}}\n</ul>\n"}]
Use the DELETE method to remove a view:
curl -u penelope:mypassword -X DELETE http://localhost:8080/basil/s50nwb9679dd/view/list
{"message":"View deleted: http://localhost:8080/basil/s50nwb9679dd/view/name","location":"http://localhost:8080/basil/s50nwb9679dd/view/name"}
See and manage basic documentation for your API, namely a label and a description. For example:
$ echo "This API lists the concepts associated with a given DBPedia entity" >doc.txt
$ curl -u penelope:mypassword -X PUT http://localhost:8080/basil/s50nwb9679dd/docs -H "X-Basil-Name: Concepts of entity" -T doc.txt
{"message":"Created: http://localhost:8080/basil/s50nwb9679dd/docs","location":"http://localhost:8080/basil/s50nwb9679dd/docs"}
Access to the Swagger API specification. By invoking the URL via command line the JSON specification is returned. Using a Web Browser the HTML GUI is returned instead.
$ curl http://localhost:8080/basil/s50nwb9679dd/api-docs
See and manage basic alias paths for your API. For example:
$ echo "my-api-alias\
another-alias" >alias.txt
$ curl -u penelope:mypassword -X PUT http://localhost:8080/basil/s50nwb9679dd/alias -T alias.txt
{"message":"Created: http://localhost:8080/basil/s50nwb9679dd/alias","location":"http://localhost:8080/basil/s50nwb9679dd/alias"}
You can now call any operation on the api using the alias:
$ curl -X GET http://localhost:8080/basil/my-api-alias/api
To return the list of alias:
$ curl http://localhost:8080/basil/s50nwb9679dd/alias
or, obviously
$ curl http://localhost:8080/basil/my-api-alias/alias
To delete all alias (including the one used in the url):
$ curl -X DELETE http://localhost:8080/basil/my-api-alias/alias