Page History

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

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

...

• DOCUMENT_BY_UNID
• DOCUMENT_FROM_VIEW_BY_KEY

• DOCUMENTS_BY_SEARCH_FT_PAGED

• DOCUMENTS_BY_FORMULA_PAGED

• DOCUMENTS_BY_VIEW_PAGED

• DOCUMENTS_FROM_VIEW_BY_KEY_PAGED
• VIEWENTRIES_PAGED
• VIEWENTRIES_BY_CATEGORY_PAGED
• ATTACHMENT

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

• DOCUMENTS_BY_SEARCH_FT
• DOCUMENTS_BY_FORMULA
• DOCUMENTS_BY_VIEW
• DOCUMENTS_FROM_VIEW_BY_KEY
• VIEWENTRIES
• VIEWENTRIES_BY_CATEGORY

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

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

...

Example route

Let's try to create a simple GET route: assuming we have a view named (Topics) in our test database containing , and it contains some documents with the Topic field Topic in them, then we can enter this to in 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

...

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

This example used a non-page strategy, which returns all relevant data at once. When the number of documents in the application is higher than just application contains more than a few documents, it might be better not to read all of them with one call.

If we change strategy to the example to use a paged strategy such as 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 the 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 The 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" 
		}
	]
}

...