Auf dieser Website werden Cookies gesetzt, die für den sicheren Betrieb technisch erforderlich sind. Siehe: Datenschutz

REST Services with the XPages Extension Library

by Thomas,
assono GmbH, Standort Kiel,

Domino-Designer-Logo-small.png The usage of REST based services is a great possibilty to integrate other systems and applications with the Lotus Domino Server.
This blog entry outlines the meaning and advantages of REST and shows you the basics of using the REST controls shipped with the XPages Extension Library.

REST based (or RESTful) web serivces are useful for integration scenarios as well as providing data to external applications.
I used the REST services for example recently to provide a data interface for a mobile application.

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
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

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

Some of the gerenal advantages of RESTful
services are:

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

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:

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

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:

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).

A picture named M2

Some properties of the control:

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

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:

A picture named M3

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

I called my database "Test1.nsf"
and my XPage "data.xsp". So my URL is:


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":

A picture named M4

In the response there are JSON properties
that have an @-sign before the name indicating a system (non-user-defined)

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 "" in the
extension library

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).

A picture named M5

The following properties are set:

To test the new service I open the following
URL in the RESTClient (the UNID can be copied from the view service response):


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

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

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:
A picture named M6

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.

A picture named M7

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.

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

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.

Technical article XPages Development

You have questions about this article? Contact us:

Sie wollen eine individuelle Beratung oder einen Workshop? Read more

More interesting entries

Any questions? Contact us.

If you want to know more about our offers, you can contact us at any time. There are several ways to contact us for a non-binding first consultation.

assono GmbH

Location Kiel (headquarters)
assono GmbH
Lise-Meitner-Straße 1–7
24223 Schwentinental

Location Hamburg
assono GmbH
Bornkampsweg 58
22761 Hamburg

Phone numbers:
Human resources department: +49 4307 900 407
Marketing department: +49 4307 900 402

E-Mail adresses: