Theatre API

You can also access the Linked Data Theatre from an API point of view. The Theatre support the most common operations.

GET

Dereferenceable resources

Get operations can be performed against any know resource. Use content negotation to retrieve your desired result.

curl -X GET -H "accept: text/turtle" http://localhost:8080/id/character/Gandalf

This will result in a 303 See Other http response and a Location field with the value http://localhost:8080/doc/character/Gandalf, because in this case a non-information resource is requested. By adding a -L switch, curl with automatically look at the new location (like your browser will):

curl -L -X GET -H "accept: text/turtle" http://localhost:8080/id/character/Gandalf

The request above will yield the same result as the request below:

curl -X GET -H "accept: text/turtle" http://localhost:8080/doc/character/Gandalf

A 406 Not Acceptable error will be returned whenever the requested format cannot be returned. In such a case, the Link field will contains links to retrieve an alternative format.

A 404 Not Found error will be returned if the requested resource doesn't exist.

Query representations

Not only dereferenceable URI's can be used. Any representation can be retrieved via the Theatre API. Typically, these representations contain /query in the URL.

In case a representation contains multiple parts, only the first part will be used to return data. A "SELECT" query will return a binding set (sparql-result-set), A "CONSTRUCT" query will return a set of triples (rdf).

You might use the generic content types application/xml or application/json to let the theatre decide which particular XMl or JSON representation should be returned. This will avoid any 406 Not Acceptable errors.

curl -X GET -H "accept: application/xml" http://localhost:8080/query/SelectFormats"

PUT

Non-translator containers

Put operations can be performed against any predefined container. The body of the request will be used to replace the content of the container. This means that a named graph with the same URI as the container will be updated.

Use the Content-type header to specify the format of the request body. If no content-type is given, the API assumes that the format is turtle.

Us the accept header to specify the format of the response. If no accept header is given, the API assumes that the format should be plain text.

It is also possible to send a zip file to a container. The zip file may contain one or more files that should be added to the container. The files may be of different formats. A well known extension should be used for these files (like .xml, .ttl or .jsonld). To upload a zip file, use the content-type multipart/x-zip.

Some examples:

curl -X PUT -H "Content-type: application/ld+json" -T example.jsonld http://localhost:8080/container/simple
curl -X PUT -H "Content-type: multipart/x-zip" -T files.zip http://localhost:8080/container/simple
curl -X PUT -H "accept: application/json" -T example.ttl http://localhost:8080/container/simple

A 200 Ok response is given whenever the upload is succesful.

A 409 Conflict response is given when some error occurs. The response body will contain more information about the specific error.

Translator containers

PUT (and POST) can also be used with containers that are supposed to translate the uploaded data. In this case, the uploaded content should contain the data in the format that the translator expects. At this moment, only XML formats are expected. A Content-type header is not needed.

The example below will upload an Archimate XML document to the Theatre:

curl -X PUT -T LDT.archimate http://localhost:8080/container/archi

The specification of this archi-container is given below:

<http://localhost:8080/container/archi> a elmo:Container;
	elmo:translator elmo:ArchiTranslator;
.

POST

Post operations can be performed against any predefined container. The operations works exactly the same as a Put operation, with one difference: a post operation doesn't replace the content of the container, but will merge the triples in the request body with the triples already in the container.