Architecture - Opera XML Store
Index
Introduction
This document is intended if you want to understand more about what is going on behind the scenes and how you best can interact with the Opera XML Store. The structure is intended to be easy to follow, so that you as a developer quickly can read up on the most relevant parts.
All data operations on the Opera XML Store are performed in a consistent manner, following the REST-based access pattern below. Example: The HTTP methods that can be used, are:
- POST - Create
- GET - Read
- PUT - Update
- DELETE - Delete
These HTTP methods covers the basic data operations; Create, Read, Update and Delete, and is often refered to as CRUD.
Before you can go ahead and perform these operations, there are a couple of small, but important details. First of all you will have to send the correct Content-Type when creating or updating data. Second you will have to define the correct Accept header signaling the format you want to returned. See the Technical reference - Special headers for more information.
Data can be retrieved as both XML and HTML, data can only be created or updated using the XML data format specified for the data model in question.
Before you can access other features then reading public data, you need to be logged in. This is easily done in your browser by going to the login page, where you will find a standard login form.
If you are accessing from a widget you should send the extra HTTP header X-Http-Accept-Override: text/xml. You will then get an XML response back, either with a statuscode of 401, (meaning authentication failed) or status code 200, you successfully logged in.
Performing data operations
To make it simpler to follow the disussion, this document will use the Notes data model as it is a very simple data model having only two elements: Title and content.
Adding a new document
When you want to create a new item, you do a HTTP POST. The XML data you want to represent the new document, need to be well-formed and follow the schema for the data model. The schema can be downloaded under the specification's own page. For notes, go to http://xmlstore.labs.opera.com/help/datamodelinfo/notes
Example of a note:
Now that we have the data ready for sending, we can send it off to the Opera XML Store. We do a HTTP POST with the content above, making the request look like the example below:
The content type header Content-type: text/xml, specifies that we are sending XML data. If we do not, the Opera XML store will not know what you are trying to send it. The X-Http-Accept-Override: text/xml specifies that we want the response as XML.
If all went well, this would give us a response back similiar to:
Next we will look at how we can read data.
Reading data
Looking back at the general access pattern, fetching data is done issuing a GET request to the Opera Xml Store, like this:
Request:
This will give you a list of all the notes that is in your notes collection. If you have not inserted any data yet, the result set will be empty, like illustrated below:
Response:
If you followed the receipe for adding a new item above, the request should now give you:
This gives you a basic listing of what can be found in this collection. However, to gain more control over what you want to see, you can append the query parameter q and specify an XPath query allowing you to refine the results. Next, we will go through a few read examples.
Say that we want to see the entire content of all our notes. According to standard XPath we then could do a query like /n:note and the request would look like the example below:
Request: Response:Or if all we wanted was the content, the query would look like //n:note/n:content. So again, just changing the query, this would give us:
Request: Response:No title is included in the result this time, as we only requested the content
If you want to just fetch the first item then you could send a XPath query like [1], like so:
Or for the last one:
You could also combine these techniques, so for fetching the title of the next to last item:
Appending to a document
Appending data to an existing document is much the same as adding a new one. You still do a HTTP POST, but this time you need to specify some more information. First you need to know the document to append to. The document is identified by the md:id attribute. So to identify it we append the item id to the URL. Youl also need to specify the parameter q holding the XPath query defining the target inside the item for the append operation. A top of that you have to say what version of the item you are modifying, so that you do not accidently change something at the same time someone else tries to modify it. Still with me? Don't worry, the next example should clear things up:
Request:Notice that we need to wrap the update content in an 'update' element as the update itself is not valid XML.
Response:If we query the item like previously described using the query /n:note, we can see that it has changed:
Updating an entire document
You can update the entire contents of a document by using PUT and not specifying a query.
Request: Response:If we query the collection again, using the query /n:note, we can see that it has changed yet again:
Partially updating a document
To do a partial update of an item is exactly the same as replacing the whole item, except you this time specify an XPath query to target what you want to overwrite.
Request: Response:Querying the collection, using the query /n:note, we can see the changes:
Deleting a document
Request: Response:Deleting parts of a document
You can delete parts of a document by using the same procedure as above, but by specifying an XPath query, you can control what parts will be removed.
Note: It may be a good idea to see what will be deleted using GET first, and the issue a delete if you are happy with the result.
That was the last of the data operations. Next, let's look at some other features the Opera XML Store has to offer.
Clear collection
You can clear an entire collection by specifying the collection without specifying a document id, like this:
That was the last of the data operations. Next, let's look at some other features the Opera XML Store has to offer.
Additional features
The Opera XML Store is intended to be a flexible and powerful way of storing your data. We have already been through the vanilla functions, but there is more to it as you will see next.
Sharing data
By default, only you can create, read, update and delete your data. However, if you want to, you can give other users access to the previously mentioned operations: Create, Read, Update and Delete. Be careful when giving access groups where you might not know all particapants, especially when it comes to data destructable operations like modify and delete. The is also a special permission called "modify own" which if set allows other users to modify the documents they have created in your collection. This setting will of course do nothing if you do not also grant the same users the permission to create as well.
The groups are the same as in the My Opera community, and you will have the possibility to grant access to any and all groups that you are member of. Just select permissions in the top menu, and select the data collection you want to set permissions for. The permissions can also be set using XML requests, as you can see in the next section.
So how to access someone else's data? You do it exactly as shown in the previous examples, but switch the username with username of the user you want to access. Simple as that!
Setting share permissions
As you might want to change the permissions for a collection of data, like notes, you can do this both through the HTML interface or using an XML version of the same interface, suitable for widgets. The URL is always the same: http://[host]/permissions/<data-model-alias>
If you do a HTTP GET, and is setting the correct Accept header (X-Http-Accept-Override) to text/xml:
Request:
You will receive XML data that resembles the following snippet:
Response:
If you want to update it, change the relevant permission(s), and and send it back, using an HTTP POST, like this:
Request:
Done correctly you have now updated your permission set, and you should receive a message like:
Response:
Notice that you do not have to send back all groups, only those present in the update request are considered. Groups not present will stay unchanged.
Browsing the data
As not all platforms or browsers support widgets or other means of utilizing the Opera XML Store, it supports basic viewing of stored data as HTML. This is possible doing an XSL transformation of the data, displaying the data so that it is easily readable using a limited browser or device. This is also useful for debugging, as it allows you to see excatly what data is stored.
Conclusion
The above examples should be enough to get you started. Should you have problems and need help, or just have other feedback , this is most welcome! Please also keep in mind that the specifications may change over time and that there is no guarantee of data security or integrity, so don't store the access code to your house-safe in here.
Good luck!