Usability - Productivity - Business - The web - Singapore & Twins

Custom REST service in XPages using a service bean

Talking to your backend using JSON and REST is all the rage for contemporary development. Domino has supported, at least reading, this access for quite a while using ?ReadViewEntries[&OutputFormat=JSON]. Using Domino Access Services (DAS) this has been extended to read/write support for documents as well.
However, as a result, your front-end application now needs to deal with the Domino way to present data, especially the odd use of @ in JSON keys (which e.g. jquery isn't fond of). Contemporary approaches mandate that you minimize the data you send over the wire and send data in your business structure, not in your database format. Furthermore, when sending data back, you want to validate and act on the data.
In the Extension Library there is the REST control, that you can use instead of the DAS service. It allows you to define what you want to expose as XML or JSON. There are a number of predefined service, but my favorite is the customRestService. When you use the custom service, you can write JavaScript for all events happening: doGet, doPost, doPut and doDelete, but you also can use a service bean. A service bean is not a managed bean, so you don't need to specify anything in your faces-config.xml. However it is a little special. A sample XPage could look like this:

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core"
 <h1>This is the landing page of the orgSearch Service</h1>
 <p>Please use "search.xsp/json" for the actual query</p>

 <xe:restService id="JSONSearch" pathInfo="json" state="false">
   <xe:customRestService contentType="application/json"
if your page name is demo.xsp then the access to the service based on the pathInfo property is demo.xsp/json.To implement the service bean your java class needs to extend the CustomServiceBean. There is only one method you need to overwrite: renderService. It gives you access to the CustomService object, that sits on the XPage and the RestServiceEngine, that provides access to the request/response. It can look like this:

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.ibm.domino.services.ServiceException;
import com.ibm.domino.services.rest.RestServiceEngine;
import com.ibm.xsp.extlib.component.rest.CustomService;
import com.ibm.xsp.extlib.component.rest.CustomServiceBean;

public class CustomSearchHelper extends CustomServiceBean {

 public void renderService(CustomService service, RestServiceEngine engine) throws ServiceException {

  HttpServletRequest request = engine.getHttpRequest();
  HttpServletResponse response = engine.getHttpResponse();

  response.setHeader("Content-Type", "application/json; charset=UTF-8");

  // Your code goes here!



You need to extract the method (GET, POST, PUT, DELETE) from the HttpServletRequest so you can take the appropriate action.
As usual YMMV

Posted by on 22 October 2014 | Comments (6) | categories: XPages


  1. posted by Miguel Calvo on Thursday 23 October 2014 AD:
    I completelly agree, but that's not always, in some customers, possible. Emoticon smile.gif
  2. posted by Miguel Calvo on Thursday 23 October 2014 AD:
    I must advise to anyone that want to try this code, that you need at least IBM Domino 9 or Lotus Domino 8.5.3 + ExtensionLibraryOpenNTF-853.20120126-0415

    It won't work on Lotus Domino 8.5.3 + UP1.

    The error in the server console will be:
    "Cannot find the library "com.ibm.xsp.extlib.library" with tag version 8.5.32001, to be used by the page/xpagename.xsp. The library tag version is blank"

    Stephan, interesting and useful content, as always.

  3. posted by Stephan H. Wissel on Thursday 23 October 2014 AD:
    Anyone in his right mind will upgrade to 9.0x these days to get the SSL Poodle mitigated, so no point trying to be backward compatible Emoticon smile.gif
  4. posted by Patrick Kwinten on Friday 19 June 2015 AD:
    is it possible to get a more complete example for the put/post/.. options?
  5. posted by Malin Anderson on Wednesday 16 March 2016 AD:
    I do not understand what code I should write after setting the header to produce json output.

    Can you provide a simple example?
  6. posted by Stephan on Friday 18 March 2016 AD:
    I usually use the Google GSON library. You will find PLENTY of examples there: { Link }