My First REST API

Idea

Let’s get started and turn the Domino Directory into a microservice which provides person data in JSON format.

We start small and only get the firstname, lastname, the list of usernames and the email.

We don’t want to touch any design elements of the domino directory (data source).

The user / system makes a http request to smart.nsf. smart.nsf contacts the data source, gets the data and does some field mapping. The resulting JSON stream is being provided to the caller.

Configuration

After the successful software installation (server and designer client), we start with creating a new REST API application.

Create a new application:

Open the application in the notes designer and activate the library. Open the 'Xsp Properties' located under 'Application Configuration':

Open the application in the designer and open the new design element 'XRest API Routes' under 'Application Configuration'. Copy the code and paste it into that document.

This is the code of our first route

//XPages REST API Routes - please activate org.openntf.xrest.library
router.trace(true)

router.GET('users') {
	strategy (DOCUMENTS_BY_VIEW) {
		databaseName('names.nsf')
		viewName('People')
	}
	description '<b>Domino Directory -> get all users</b>'
	mapJson 'UNID', json:'unid', type:'STRING', isformula:true, formula:'@Text(@DocumentUniqueID)'
	mapJson 'FirstName', json:'firstname', type:'STRING'
	mapJson 'LastName', json:'lastname', type:'STRING'
	mapJson 'FullName', json:'fullname', type:'ARRAY_OF_STRING'
	mapJson 'InternetAddress', json:'email', type:'STRING'
}

Save and Close and Build.

The route looks like this:

Further explanations

It is a GET route and it is named 'users'.

Notice in the strategy configuration that we have to configure the target application and the view name.

In the mapping we define the Notes field names and the according resulting JSON property like so:

mapJson 'LastName', json:'lastname', type:'STRING'

Testing

Let's test our first REST API just with any browser you wish. Open your preferred browser and go to:

http://localhost/rest/myfirst.nsf/xsp/.xrest/users

http://

localhost

rest/myfirst.nsf

xsp/.xrest

users

Depending on your configuration it might be https://

Servers hostname

Folder / filename which points to your smartNSF

Fixed string

name of the route, must correspond to router.GET('users')

If you have not modified the ACL of the myfirst.nsf yet, you get the prompt to enter your web credentials. Enter them. Make sure, that you also have the required access to the domino server’s directory (data source).

After providing them, you should get the data as a JSON response saying something like:

Congratulations, you did your first REST API using smartNSF.

What have we learned?

    We do NOT have to modify the code in the source application.
    It is very easy and fast to create a simple REST API. Isn’t it ?
    In the mapping (notes fieldname to JSON property), you can also evaluate notes formula.