Technical reference

You are here: » Home » Help » Technical reference

Technical reference - Opera Xml Store

This document is intended as a reference for developers using the Opera XML Store.

Index

Data exchange

All operations on the Opera XML Store are performed in a consistent manner, following the REST-based access pattern below. Example:

Response status codes

Below is the list of the status codes used by the Opera XML Store.

The Opera XML Store will allways return a HTTP status code 200 even though there might have accored an error. To be able to return information about what went wrong, the response XML will hold the real status code and any additional information like a more explainatory error message.

Example:
200OK. The request completed successfully
201Created. The item was created successfully
400Invalid request. Unable to process because of missing, invalid or non-supported parameter(s)
401Authentication required
403Forbidden. You do not have access to this resource
404Not found. The resource, like the application profile and/or the item name was not found
409Conflict. The version number submitted does not match the latest version
500Internal server error. This means that the was either an internal and/or unexpected error

Supported request parameters

For specifiying additional parameters, the Opera XML Store accepts the following query parameters:

qDefines an XPath query to query the specified resource for
versionDefines the latest version retrieved. This paramter must be present for all operations except read
userDefines which user's data to query if you attempt to query someone else's data. Requires that the specified user has granted you access
xsl-stylesheet"none" defines that noe XSLT transformation will be performed, returning only plain XML. Note that this does not support the specification of arbitary stylesheets.
offsetThe result offset, i.e. the start index
maxThe max number of entries returned
orderbyThe XPath expression to sort by, relative to the query target
sortorderThe direction to sort. Valid values include "asc" and "desc" for ascending and descending sorting, respectivly

Special headers

The Opera XML store is REST based, but as there are limitations on the client side, in different browsers/widgets, a set of override headers are provided. If the client is incapable of doing true PUT or DELETE requests, you can use the HTTP method override header: Also, to be able to define the content-type of the response from the server, you can use:

Please note that if the client fully support sending the above "real" header, i.e. Accept, then this is the preferred way.

Concurrency support

As data can be written (updated, replaced, deleted) from multiple clients at the same time, versioning is introduced to avoid overwrites. The scheme used is called optimistic concurrency.

The stateless nature of HTTP makes locking infeasible for web user interfaces. It's common for a user to start editing a record, then leave without following a "cancel" or "logout" link. If locking is used, other users who attempt to edit the same record must wait until the first user's lock expires. OCC is a natural choice. It is simple to implement and avoids unnecessary waiting or silently overwritten records. Typically the form presented to the user includes a hidden field with the record's original content, a timestamp, a sequence number, or an opaque token. On submit, this is compared against the database. If it differs, the conflict resolution algorithm is invoked. - Wikipedia

Document meta data

To make it possible to keep track of the data stored, who created them and who owns them, each resource is tagged with meta data. Each document/partial document you retrieve will have this set of meta data attached:

Example: