13.08.2012

>>Author:  Thomas Ladehoff
>>Ort:     Kiel (Schwentinental)
        

RESTful web services (if you don't know about them, yet)

Representational State Transfer (REST) is an software architecture style described by Roy Thomas Fielding in his dissertation. It conforms to the architecture of the Internet with its HTTP protocol.
More precisely, one could say that the HTTP protocol which is used in the Internet and in RESTful web services is an implementation of the REST architecture style.

So if you know the principles of the HTTP protocol you also know much about REST. To sum up the most important points:

• Information is provided by resources. Every resource is accessible via an unique ID (the URL)
• "Respresentational" means, that the information is transfered in certain representions in technical meaning (e.g. JSON, XML) as well as with regard to contents (e.g. text, images).
• Stateless. The server keeps no session status over a series of requests.
• Resources can contain links to other resources, enabling navigation.
• Operation on a rescource is possible by the use of a defined set of generic methods, typically
  • GET - read access to a resource, no side effects
  • POST - create a new resource
  • PUT - create or update a certain resource (certain ID)
  • DELETE - delete a resource

RESTful web services provide a HTTP based service that follows the mentioned properties.


Some of the gerenal advantages of RESTful services are:

• Loose coupling of applications and systems (leads to high interoperability)
• Easy resource oriented concept with few genereic methods
• Good scalability
• Easy caching

These are essentially also the advantages of the HTTP potocol in general

REST based services for accessing Domino data

A good overview of the REST functionality can be found in the video "REST Services for Domino and XPages" on the extension library homepage.
Here I will explain in particular the way of using the XPages controls for REST. There are also two other ways that don't require a XPages context (using directly the built-in Domino Data Service and creating a custom servlet).


There are several XPages controls that you can utilize to access Domino data, for example:

• Database Collection Service (xe:databaseCollectionJsonService): read database list on the server
• View Collection ervice (xe:viewCollectionJsonService): read list of views and folders in a database
• View Service (xe:viewJsonService): read view or folder data (with filtering), create, update and delete documents (limited)
• Document Service (xe:documentJsonService): operate on documents

As you may guess, the "Json" within the tag names of the controls indicates the usage of the JSON format for sending the data.

You can find examples of the controls in the example database within the extension library download.

For the XPages REST controls you don't need to configure anything on the Domino server (but for convenience you could, if we will see later).
Just create a XPage, drag and drop the desired REST controls and you will be able to access the service.

To show this in more detail and explain the most important parameters, we will use a very simple sample scenario with one form 'company' and a view 'companiesByName'.

The services we need to operate on the company documents in a convenient way are:

• xe:viewJsonService (list existing companies)
• xe:documentJsonService (create, read, update, delete a certain company document)

We could also have used the view JSON service to update documents, but then you are limited to only those columns, that map directly to fields in the document.
With the document JSON service we can even operate with rich text fields and attachments.

Accessing the view data

We start with an empty XPage and add the REST service control (see screenshot).


Some properties of the control:

• ignoreRequestParams: parameters in the url are ignored for the rest service (you probably know that from the XPages data sources)
• pathInfo: This is a string that identifies your service on the XPage. For the view JSON service in this example it is named "companies".
• service: Here you can assign exactly one concrete rest service, choosing from the given list (see screenshot)

The properties of the view JSON service are almost self-explanatory, but to mention a few ones that should be taken into account:

• columns: this property takes elements of the type xe:restViewColumn, which in turn has a property "columnName" (reference to the view column) and "name" (property name of the JSON Object in the output). This mapping applies only to GET requests. There is also a "value" property here, where the output can be computed.
• defaultColumns: if true, all columns in the view will be used
• systemColumns: Special system values, not necessarily available explicit as a view column (e.g. UNID, Form, Response)
• viewName: Name of the view to use for that service

There are also some properties for filter operations, like "start" and "count" to implement paging or "search" to do a full text search on the view content.
An addition there are properties for reacting on document events (like querySaveDocument), which will be explained in the section dealing with the document service.

The following screenshot shows the view service properties, used in the example:

Test the API

To access the service, the string set for the "pathInfo" property must be used. The general URL schema in XPage context is:
http://{host}/{database}/{XPage name}/{pathInfo}/unid/{unid}?{parameters}

For the view service in this example we don't want to access single documents and thus can leave out the UNID part.
I called my database "Test1.nsf" and my XPage "data.xsp". So my URL is:
http://localhost/Test1.nsf/data.xsp/companies

The URL can be requested by entering it directly into the browser address bar (request method GET) and the entries in the view should be returned in JSON format.

There is also a nice tool to test the API quickly and to see if everything works as expected. It's a Firefox add-on called RESTClient,
which let's you specify the HTTP method, URL, request headers and request body. After sending the request, the response from the server is displayed.

The following screenshot shows the response in the RESTClient from the view service "companies":



In the response there are JSON properties that have an @-sign before the name indicating a system (non-user-defined) column.
The different data types have different representation formats, for example a string is enclosed in quotes, a number is not.
A detailed description can be found in the documentation (file "DominoDataServiceDoc.zip" in the extension library download).

Operate on documents

To provide the API part for single documents, a second REST service control has to be added to the XPage. This time the "pathInfo" property is "company" and the concrete service is the document service (xe:documentJsonService).




The following properties are set:

• compact: If "true", the output will not contain any whitespaces (saves bytes)
• defaultItems: If "true", all items and some metadata will be included in the output
• formName: Name of the form to use, when creating new documents

To test the new service I open the following URL in the RESTClient (the UNID can be copied from the view service response):
http://localhost/Test1.nsf/data.xsp/company/unid/56A63CD8312606F8C1257A54004009DD

The result should now contain every field in the form plus some meta information (e.g. properties @unid, @form, $UpdatedBy).

The next step is updating an existing document. Updating is usually done via the HTTP PUT method. The Extension Library implementation handles this in a special way. It uses the PUT method to replace the current document content with the data in the request, discarding all previous content.
But in most of the times you probably want to update some items and leave the rest of the document untouched. This is realized in the Extension Library with another HTTP method called "PATCH".

At this point it's worth mentioning that the Domino server by default only allows GET and POST requests. Allowing also the other methods is no problem via an Internet site document, but you could also take an alternative approach that also comes in handy, if your client doesn't support PATCH requests.
The HTTP methods PUT, PATCH and DELETE can alternatively be replaced by the POST method and an additional HTTP header called "X-HTTP-Method-Override" that in turn specifies the method to use.

So, how to test updating an item in a certain document with the RESTClient?

1. Setting the mehtod override header
In the RESTClient select from the title bar: Headers -> Custom Header
Then filling out the dialog as shown in the screenshot:

2. There is another header, that needs to be set. Otherwise the server won't accept the request.
This is about the content type of the request, that needs to indicate JSON format:
Header name: Content-Type
Header value: application/json

3. GET a certain document (just to have data for updating).

4. Change the request method to POST and make sure the headers are set.

5. Set the data, you want to update in the request body.



6. Click "Send" and if you don't get an error message you can check the result by switching back to the GET method to see the updated value.



Other operations:
Create a new document: set the HTTP method to POST (without X-HTTP-Method-Override header)
DELETE a document: set the HTTP method to DELETE (or method POST and X-HTTP-Method-Override header to DELETE)

Programmatically extend the functionality of the document service

If you want to hook into the request processing, one possibility is the use of the document events like "querySaveDocument".
This way you can do additional tasks and change or add document data.

The following list is an overview over the parameters of the different methods.

• queryNewDocument: no parameters
• queryOpenDocument: parameter 'id' (type String)
• querySaveDocument: parameter 'document' (type lotus.domino.Document)
• queryDeleteDocument: paramter 'id' (type String)
• postNewDocument: parameter 'document' (type lotus.domino.Document)
• postOpenDocument: parameter 'document' (type lotus.domino.Document)
• postSaveDocument: parameter 'document' (type lotus.domino.Document)
• postDeleteDocument: paramter 'id' (type String)

If you want to abort the request processing, all methods starting with 'query' support a Boolean return value. When the return value is 'false', an exception will be thrown and an error message will be returned to the client. When it is true, the processing will be continued.

If you need more control about what happens and the generated output, you could also create a custom servlet. How to do this, will be part of a future blog entry.