API Specification

This document specified the URL paths available, the methods that they accept, the expected behaviour, HTTP response headers and returned data.

Paths

Each server can run a number of modules that bind to paths. The defaults are documented here.

/webbox

Hosts a webbox for a user.

WebBox stores files in the URI that they are uploaded to. The are handled differently if they specify an RDF content-type.

WebBox supports the following methods for the following content-types:

application/rdf+xml

• GET /webbox/[path]

Retrieve a resource (as application/rdf+xml).

• PUT /webbox/[path]

Create a new resource with the supplied data.

• POST /webbox/[path]

Update an existing resource with the supplied data.

Optional GET query parameters

• graph=[URI]

Specify the graph that the PUT or POSTed data will be saved into. This is intended for application authors that wish to update information to named graphs that control.

By default, new data is saved into the "received graph" which has URI:

http://webbox.ecs.soton.ac.uk/ns#ReceivedGraph

which acts as a holding graph for data from unknown parties.

any other content-type

• GET /webbox/[path]

Retrieve a file.

• PUT /webbox/[path]

Create a new file.

• POST /webbox/[path]

Update an existing file.

/update

Access to the repository-wide journal.

/certificates

X509 certificate and encryption key generation.

WebBox specific Data

WebBox supports messaging and subscriptions, and parses asserted RDF to support these.

Messaging/WebID

To send a message you need the WebID of the recipient.

The WebID is the URI of a person. For example the WebID of Daniel Alexander Smith is:

http://danielsmith.eu/me#dan

In order to determine the endpoint URL of their WebBox, you can use the WebBox ontology.

We use webbox as a prefix for the webbox ontology:

http://webbox.ecs.soton.ac.uk/ns#

To specify that the webbox address of Daniel is https://data.ld.is/webbox, you can assert the triple:

<http://danielsmith.eu/me#dan> webbox:address <https://data.ld.is/webbox>

You can also specify Daniel's WebID without asserting that triple yourself, because that triple is asserted into the linked data, which is available at his uri (http://danielsmith.eu/me#dan), and WebBox will attempt to resolve the URI before sending the message.

Thus, to easily receive WebBox communications from others, you should add the webbox:address triple to your WebID/FOAF file.

Messaging/Messages

Messages are sent using the sioc:addressed_to predicate. For example, if I want to send the URI for Southampton (http://dbpedia.org/resource/Southampton) to Daniel, I assert the following triple into my WebBox:

<http://dbpedia.org/resource/Southampton> sioc:addressed_to <http://danielsmith.eu/me#dan>

Daniel's WebBox will then resolve his URI (see above) and connect to his WebBox, and send this triple to him.

Upon receipt of a message, the WebBox will check to see if its URL (as set in the securestore.cfg) is the same as the message recipient's webbox:address. If they match, the WebBox knows that this is a message it need to process, and it resolves the URI, and asserts it into its store.

Subscriptions

WebBox is designed for collaboration, and as such it supports subscribing to a resource, and receiving notices when resources update. WebBox supports two predicates, webbox:subscribe_to and webbox:unsubscribe_from.

Thus, if Daniel's WebBox hosts the following URI https://data.ld.is/webbox/Southampton, we can subscribe to it by asserting the following triple to his WebBox:

<http://danielsmith.eu/me#dan> webbox:subscribe_to <https://data.ld.is/webbox/Southampton>

This tells his WebBox that whenever an update is made to the Southampton resource, that it should send the sioc:addressed_to message (see above) to the webbox of the user identified by the WebID http://danielsmith.eu/me#dan.

Likewise, a subscription can be cancelled by asserting an unsubscribe triple:

<http://danielsmith.eu/me#dan> webbox:unsubscribe_from <https://data.ld.is/webbox/Southampton>