Rest Parameters and Options - EcoSys - Customization & Programming - Hexagon PPM

EcoSys Web Service API Usage Documentation

Search by Category
Customization & Programming
EcoSys Version

Using Paging option for Rest API

EcoSys REST API supports a paging option for the GET (read) method. When the paging option is set, the number of rows specified will be returned and a link to the next page will be included in the next response except for the last page.

Since paging option requests returning a large set of data in smaller chunks, it reduces the load and memory usage of the system.


In the URL below, request an API return data with a pageSize of 100.,


The response would have the next page element as follows:









</ SampleProjectResult >

Gateway will make the API call using the specified page size and return all objects into an output file by automatically retrieving the next page until there are no more pages to retrieve. So the last page will not have a nextPage element, which indicates that there is no data to retrieve.

Server settings for Page Cache

You can use the server settings to control the page cache and to check any performance issues. The following are some of the server settings for REST API GET calls:

Server Setting Key

Default Value


restapi.pageCache.expirationTime (seconds)

2 times min

When the session thread runs, it looks at the last time the page was accessed in the session using the command 'restapi.pageCache.expirationTime' and logs out if the session is idle for a long time.​



Used to manage the size of the cache

restapi.pageCache.offHeapSize (MB)


Controls Off heap size

restapi.pageCache.fileSize​ (MB)


Controls page cache file size

restapi.pageCache.statistics (Boolean)


Controls cache statistics



Controls the rate at which the session cleanup thread runs

While setting restapi.pageCache.offHeapSize > 0 in your EcoSys system configuration, you must also set the Java Option ‘'-XX:MaxDirectMemorySize' in your Application Server.

The XX:MaxDirectMemorySize setting must be used with 'restapi.pageCache.offHeapSize' setting. You must set the same values for both XX:MaxDirectMemorySize and restapi.pageCache.offHeapSize.

Passing Runtime Parameters for REST

Runtime parameters for defined object views or events may be passed as URL parameters. They should be identified using the id of each defined parameter (not its caption). For lookup-type parameters, you may provide either the internal database id or the canonical display identifier (e.g. id or short name) of the referenced object.



Alternatively, you may specify runtime parameters as URL components following the name of the API. In this mode, all parameter values must be represented in their defined sequence. This mode enables a more URL-centric representation, typically for a single, uniquely identified object.

Example of alternative URL syntax:


 Due to default behavior in Apache-based application servers such as Tomcat and JBoss for encoded forward slashes ("/" as "%2F"), this syntax will not work by default if your parameter values contain encoded forward slashes, and the server will return an error response code of 404.

If parameter values containing forward slashes is a requirement, you are advised to use the URL parameter syntax above instead of URL components, or you may consider configuring your server to disable the suppression of encoded forward slashes. See relevant notes on CGI security for Tomcat and JBoss.

At this time, submitting runtime parameters via a URL-encoded message body ("application/x-www-form-urlencoded") is not supported. This means that the total length of the runtime parameter value specified on the URL is limited by the maximum URL supported by the underlying application server and client (typically around 2,000 characters).

Requesting Result Meta Data

When using REST requests in XML format, you may request additional meta data about the response by including the URL parameter "?_includeMetaData" (no value required). When this is specified, the XML document will include two additional nodes: <Meta> (contains object and attribute counts) and <Performance> (contains metrics for elapsed time, CPU time, and database time).

For more information on how the <Meta> and <Performance> nodes are formatted, refer to Result XML Format or the generated XSD. This meta data is available for both read and write requests when using REST in XML or JSON format.