-
Notifications
You must be signed in to change notification settings - Fork 16
HTTP Interface
Backstage publishes an HTTP+JSON interface to all its data and functionality.
Note that all paths below are relative to the base mount point, which is by default /backstage. Considering default ports and URI schemes, the base URI is http://myhost:8181/backstage/
The resources it exposes through this interface are:
Paths: data/mem/ and data/disk/
POSTing data to either endpoint will create a database, and if successful, return an HTTP 201 response with a Location header whose value identifies this database, for example data/mem/2a478dfe. As an URL, this value is used to link the Exhibit HTML to the database, as described in the Authoring section.
The two paths are used to distinguish between a request to create an in-memory database - data/mem/ - and a request to store it on disk - data/disk/. In general, in-memory databases will be faster than disk based databases for most operations, but that comes at the expense of increased memory usage.
The Content-Type header should be set correctly on the POST request.
For example, using curl, you would upload the provided sample Swedish Europeana dataset to your server via the following command:
curl -i -H "Content-Type: application/json" -X POST -T europeana-swe.json http://localhost:8181/backstage/data
See Authoring for a description of the data export feature.
Path: exhibit-session/
Exhibit sessions are stateful entities (that eventually timeout, etc..) created by POSTing a complex JSON document describing the configuration of the Exhibit and its components: facets, lenses, etc.. More detail will be provided later, but you can see an example for yourself by monitoring the XHR request sent from the browser displaying a Staged Exhibit.
If creation is successful, an HTTP 201 response is returned with a Location header returning a path to the session, e.g. exhibit-session/98eca470.
Once the session is created, it can be accessed via its components.
All the components of the session are available under the "component" sub hierarchy, for example exhibit-session/98eca470/component/. There is no current way to query them via HTTP GET, as the session is "owned" by the browser and uses state-changing calls to manipulate the user's current view of the Exhibit. Instead, components such as facets can have their state set using HTTP PUT; a body containing an empty object is interpreted as a request to clear any restrictions showing all items, and one containing a specific "restriction" declaration is used to explicitly apply restrictions to single facets, narrowing the view.
Responses from these PUT requests will include the revised lens data.