In my previous post I announced the framework I’ve been building the last couple of weeks to implement REST services in xPages. In theory you can drag’n’drop a restcontrol on an xpage, bind the apibean to it and you are good to go.

But of course you still need to write code that handles the incoming request. In this post I will explain to you how a normal flow will be in the framework. We will use the demo application found on github (the project is also a demo app ).

A primer

First of all you need to create a new app from the source from github. You can do so by downloading the project and associate it with a new NSF (info) When you have done this please use the agent initialize agent to create the default keywords used by the application.

Next of you can go to index.php and you will be able to add measurements from your energy usage ( electricity / gas / water ). The application supports get, post, put and delete of the very simple measurement object.

All you see at the frontend is bootstrapped and pure javascript

The POST request

So what happens if you enter a date, a value and hit the save button? The framework will go through the following flow (warning! Huge image )

as you can see here a lot is going on. First of all the framework will search if there is a router object that can handle the current endpoint ( ie. /measurement ). If such an entry is found it will forward the request to this object.

This gives you the ability to concentrate the logic that belongs to that endpoint in a single tree of objects. Removing that tree won’t break the api framework only removes the endpoint. If implemented correct you dont end up with 4 methods ( get, post, put, delete ) in the base class (apibean) too handke lots of endpoints. Every endpoint has its own class tree.

Depending the mehod executing the input data is being parsed by the inputhandler object. This is by default a JSON object. The data is being validated ( not in the image ) by so called validators and if this all works out the dataservice object that is going to talk to domino / mysql / other db system is doing its job.

There are , as you can see , several layers where things are happening and the succes of 1 layer decides the flow of the other layers. If there is an error with parsing the request body the dataservice will not be accessed etc etc.

This concludes this post. I hope you have a little understanding of how the framework, at a very high level, does its thing. In the next chapter I will explain to you how to add a new endpoint to the application.

Stay tuned