-
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/disk
The name for the database - the string used to distinguish one database from the next, e.g. "2a478dfe" in the example above - can be set manually using the Slug HTTP request header. So if we wanted to set the name for the previous request, we would use this request, which would place the data at /data/disk/eurswe;
curl -i -H "Content-Type: application/json" -H "Slug: eurswe" -X POST -T europeana-swe.json http://localhost:8181/backstage/data/disk
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.