Part 5 :: Create a REST api to update and create documents

In this part, we will create another api to update existing and to create new tasks.
Open your Xpage api and drag & drop another REST service to it:

The pathInfo is now updateData, select service type customRestService, content Type application/json and enter api.UpdateService as service Bean name:


The java class UpdateService can be simply copied and renamed from our existing DataService or you can create a new one.


In this class we handle a POST request, which means we get some data from the client calling this service. We need another package called commons-io. Download and import it, or copy it from the provided demo application.


Now you can copy&paste this code to your UpdateService class:

package api;

import javax.servlet.ServletInputStream;
import javax.servlet.http.HttpServletResponse;
import lotus.domino.Database;
import lotus.domino.DateTime;
import lotus.domino.Document;
import lotus.domino.Session;
import lotus.domino.View;

import org.json.JSONArray;
import org.json.JSONObject;

public class UpdateService extends CustomServiceBean {

	public void renderService(CustomService service, RestServiceEngine engine) throws ServiceException {
		try {
			//Create a JSONObject from the incoming data
			String json_string = IOUtils.toString(engine.getHttpRequest().getInputStream(), "UTF-8");
			JSONObject json = new JSONObject(json_string);

			//TODO: You should do some checks here to verify, if the incoming data is valid

			//Create a Domino session
			Session session = ExtLibUtil.getCurrentSessionAsSignerWithFullAccess();
			Database thisdb = session.getCurrentDatabase();
			Document doc = null;

			//Check, if a universal id is provided
			if (json.has("universalID")) {
				//Search document by ID
				String universalID = json.getString("universalID");
				doc = thisdb.getDocumentByUNID(universalID);
				//TODO: Do some checks and errorhandling
			} else {
				//Create a new document if no universal ID has been provided
				doc = thisdb.createDocument();
				doc.replaceItemValue("Form", "task");

			//Save all provided fields
			if (json.has("status")) doc.replaceItemValue("status", json.getString("status"));
			if (json.has("topic")) doc.replaceItemValue("topic", json.getString("topic"));
			if (json.has("description")) doc.replaceItemValue("description", json.getString("description"));
			DateTime dueDate = session.createDateTime(json.getString("dueDate"));
			if (json.has("dueDate")) doc.replaceItemValue("dueDate", dueDate);,false);

			//Create a response
			HttpServletResponse response = engine.getHttpResponse();

			//Change response content type to JSON
			response.setHeader("Content-Type", "application/json; charset=UTF-8"); 

			//Send the created JSONObject as response
			response.getWriter().write("Document successfully saved/created");
		} catch (Exception e) {

At first, we convert the incoming JSON data to a JSONObject. This object contains all changes we want to save to the notes database. The JSON format is quite simple:

	"universalID": "the document universal id, ommit this property to create a new document",
	"status": "OPEN",
	"topic": "topic",
	"dueDate": "02/12/2017",
	"description": "your task description"

If we provide the property universalID, we want to update an existing document, if not we create a new one. This is again a quite simple example without error handling and validations. In production, this would be much more complex code.

You can now use your api with any REST client. Just send this JSON data to the api and a new task should be created in your Notes database:

	"status": "OPEN",
	"topic": "first task created with the REST api",
	"dueDate": "02/12/2017",
	"description": "your task description"


Now, we have the following API functionality implemented: Read data, update documents, create documents. Deleting documents is not yet implemented, you can do it as an example by your own. Bringing the parts together will be explained in part 6