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.
Example
In the URL below, request an API return data with a pageSize of 100.,
http://.../ecosys/api/?_pageSize=100
The response would have the next page element as follows:
<SampleProjectResult>
<SampleProject>
</SampleProject>
…
<nextPage>
<![CDATA[
http://.../?_pageId=a2b93782-fd47-44d0-9d53f7c81a62c395&_startRow=101&_count=100
]]>
</nextPage>
</ 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 |
Description |
|
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. |
|
restapi.pageCache.heapSize |
32 |
Used to manage the size of the cache |
|
restapi.pageCache.offHeapSize (MB) |
0 |
Controls Off heap size |
|
restapi.pageCache.fileSize (MB) |
0 |
Controls page cache file size |
|
restapi.pageCache.statistics (Boolean) |
false |
Controls cache statistics |
|
server.sessionMaintenance.intervalMinutes |
15 |
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.
Example:
http://.../restxml/Projects/?proj=ABC&startdate=2013-01-01
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:
http://.../restxml/Projects/ABC/2013-01-01
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.