Optimize REST Services API
The Optimize Restful Services API contains a variety of services that enable users to query process model and process analytics data. With these services, users can extract Optimize data for use with reports and other applications. Users should be aware that use of these services can affect Optimize performance, as many of these services perform database queries. It is recommended that all implementations be tested in a production-like environment prior to release in order to understand and evaluate potential performance impacts.
There are two components to this API as described below.
- Process Model REST API provides all the processes configured for tracking
- Process Analytics REST API provides analytic data for processes.
The API returns either XML or JSON results based on request headers, as described in the following table.
| type | HTTP Header “Content-Type” | HTTP Header “Accept” |
|---|---|---|
| json | application/json | application/json |
| xml | application/xml | application/xml |
The order of elements in the response (XML or JSON) may or may not be predefined; however, the order is subject to change and should not be relied upon when consuming the response.
Time Parameters
The input time format should comply to either ISO 8601 or Java epoch (long). See the following examples:
- ISO 8601 option 1: yyyy-MM-dd'T'HH:mm:ssZ
- ISO 8601 option 2 (with timezone offset): yyyy-MM-dd'T'HH:mm:ss-06:00
- ISO 8601 option 3 (without timezone offset): yyyy-MM-dd'T'HH:mm:ss
- Java epoch (example): 1407373267000
Max Results Parameter
When providing the max results parameter value, 0 or a negative number returns unlimited results, which can have a significant performance impact. Users should exercise caution when configuring implementations that allow unlimited results. If no max results parameter is specified, the parameter defaults to 5000.
HTTP Request Errors
Errors encountered in the request format or during its execution are returned as an HTTP response. Errors in the request format or in the content of the request parameters are caught during request validation and returned in a simple response. Unexpected errors encountered during execution are returned with more detail. Unexpected errors are also captured in the Analytic Engine log, while validation errors are not captured.
Error Response Structure
<error>
<errorMsg>error message</errorMsg>
<httpStatusCode>HTTP status code</httpStatusCode>
<trace>
stack trace if applicable
</trace>
</error>Error Response Example
<error>
<errorMsg>missing parameter [startTime]</errorMsg>
<httpStatusCode>400</httpStatusCode>
<trace/>
</error>Statistical Results
Statistical results, such as historical cycle time average, are calculated over time for a specific statistical interval. The interval is a period of time where by all historical data that falls with the time period is used in the calculation. For example, a 1-DAY interval may calculate all historical data for all Mondays, depending upon the user's configuration of the Optimize Analytic Engine. For more information about statistical intervals, see the Administering IBM webMethods Optimize guide.
The Optimize REST API service's statistical interval is determined by the service relative to the input time range parameters. Some services provide an optional input parameter for the statistical interval so the user can choose an interval that is more suitable to their use case. If the service does not provide a statistical interval input parameter, then the service will use a 1-DAY interval for the day relative to the given time range's end time. For example, if the input time range ends on Tuesday, the Tuesday statistical interval will be used. If the user does not include the optional parameter, then a suitable interval will be determined based on the size of the time range.
| Time Range | Statistical Interval |
|---|---|
| <= 12 hours | 1 hour |
| <= 2 days | 4 hours |
| <= 2 weeks | 1 day |
| <= 4 weeks | 1 week |
| > 4 weeks | 4 weeks |