Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 41 Current »

 

After installing Designer plug-in you can see new design element called XRest API Routes under Application Configuration category.

It is used for editing routes your application will be listening on for REST calls.

Basic syntax of routes.groovy

Each endpoint is defined in following way:

router.METHOD('route/path/{variable}') {
	strategy(STRATEGY_NAME){
		... strategy parameters ...
	}
	mapJson 'notesFieldName', json:'jsonFieldName', type: 'STRING|INTEGER|DOUBLE|DATETIME|ARRAY_OF_STRING|ARRAY_OF_INTEGER|ARRAY_OF_DOUBLE|ARRAY_OF_DATETIME', isformula: true/false, formula: '', readonly: true/false, writeonly: true/false
	mapJson ...
	accessPermission 'groupName1', 'groupName2', '[roleName1]', '[roleName2]', ...
 }

where METHOD is one of:

  • GET
  • POST
  • PUT
  • DELETE

and STRATEGY is one of:


Non paged strategies are available as well, but please consider using these just for small data sets, because these return all relevant data at once.

 

accessPermission: list groups and/or roles user have to be member of to be allowed to use endpoint

mapJson: list fields you want to read from documents, or formulas you want to be executed in the context of current document

 

Example route

Let's try to create simple GET route: assuming we have view named (Topics) in our test database containing some documents with field Topic in them, we can enter this to our routes.groovy file:

router.GET('docs') {
	strategy(DOCUMENTS_BY_VIEW) {
		viewName('(Topics)')
	}
	mapJson "date", json:'date', type:'DATETIME', isformula:true, formula:'@Created' 
	mapJson 'Topic', json: 'topic', type: 'STRING'
}

and access our new REST point at

http://server.name/path/database.nsf/xsp/.xrest/docs

Returned data should look like this:

{
	[
		{ "topic": "Topic 1", "date": "2017-03-03T18:28+00:00" },
		{ "topic": "Topic 2", "date": "2017-03-03T18:28+00:00" }
		...
	]
}

You can see it is basically returning content of field Topic for each document in (Topics) view.

When the number of documents in the application is higher than just a few, it might be better not to read all of them with one call.

If we change strategy to DOCUMENTS_BY_VIEW_PAGED, so we have it defined like this:

router.GET('docs') {
	strategy(DOCUMENTS_BY_VIEW_PAGED) {
		viewName('(Topics)')
	}
	mapJson 'date', json:'date', type:'DATETIME', isformula:true, formula:'@Created' 
	mapJson 'Topic', json: 'topic', type: 'STRING'
}

we can now pass parameters start and count in our URL to get just a subset of documents. For example calling

http://server.name/path/database.nsf/xsp/.xrest/docs?start=100&count=5

will return 5 documents starting at position 100 in the view. Returned JSON is a bit different:

{
	"start": 100,
	"count": 5,
	"total": 24900,
	"entries": [
		{
			"topic": "Topic 100",
			"date": "2017-03-03T18:28+00:00" 
		},
		{
			"topic": "Topic 101",
			"date": "2017-03-03T18:28+00:00" 
		},
		{
			"topic": "Topic 102",
			"date": "2017-03-03T18:28+00:00" 
		},
		{
			"topic": "Topic 103",
			"date": "2017-03-03T18:28+00:00" 
		},
		{
			"topic": "Topic 104",
			"date": "2017-03-03T18:28+00:00" 
		}
	]
}

(tick) Congratulations, you've just created REST service to access data in Domino database using SmartNSF project!

 

 

 

  • No labels