StatPro Revolution Web API
The portfolio-analysis-controller-query Link Relation
portfolio-analysis-controller-query link relation identifies a link that targets the Portfolio Analysis Controller resource, which is accessed using the HTTP POST method. This controller resource allows for triggering the (re-)calculation of Custom Time Period Portfolio Analysis resources. When triggering the calculation, an XML document is supplied in the entity body of the POSTed request which describes the time periods to request and an optional flag indicating whether or not to also trigger the (re-)calculation of any related reporting component portfolio analyses (if available). For further details of how to formulate this Xml query refer to the Querying For Data section below.
Fair Usage Policy Implications
Triggering portfolio analysis calculations is fairly resource intensive on the Revolution platform and therefore in addition to the normal Fair Usage Policy this resource has some added restrictions implemented in terms of the number of calculations that are allowed to be triggered within a period of time.
- There is a limit of ten Custom Time Period Portfolio Analyses that can be triggered per portfolio per analysis type per authenticated user within a one hour period. Any attempts to trigger more than this will result in a 403 Forbidden response being returned.
- There is also a limit of 100 time periods that are allowed per a single request. If an attempt is made to exceed this limit then this will result in a 400 Bad request response being returned.
Querying for Data
A query is expressed in XML form, and must be included in the entity body of the POSTed request to this link relation's identified URI. A query's XML looks like this:-
<customTimePeriodAnalysisRequest xmlns="http://statpro.com/2012/Revolution"> <timePeriods> <timePeriod> <start>2017-01-05</start> <end>2017-04-18</end> </timePeriod> <timePeriod> <start>2016-11-05</start> <end>2017-02-22</end> </timePeriod> </timePeriods> <applyToReportingComponents>true</applyToReportingComponents> </customTimePeriodAnalysisRequest>
In the example above, the query is requesting the calculation of a Custom Time Period Portfolio Analysis with two custom time periods. It is additionally flagging that it should also apply the same custom time periods to any reporting components alternative settings portfolios (if available).
The details and requirements of the query's XML are as follows:-
- The entity body of the request must be set to the XML document in string form. It is a bad request is the entity body is empty, doesn't contain XML, or contains invalid XML.
- Calling applications must ensure that the specified XML a) conforms to the published schema document (XSD) and b) is semantically valid.
- The start and end date must be specified in ISO 8601 format (e.g. yyyy-MM-dd). It is a bad request if any of the periods have a date specified that doesn't conform to this format.
- If the start date must be less than the end date for any one of the requested periods then this is considered a bad request.
- If any of the dates requested are outside of the range of history available for the portfolio analysis then the requested dates will be automatically adjusted to be as close as possible to the requested dates. The actual dates used will be visible in the resulting CTP portfolio analysis once the calculation has completed.
- If duplicate date periods are requested then they will only be requested once in the resulting calculation.
- Time periods can have overlapping date ranges.
- The order in which time periods are defined in the
<timePeriods>...</timePeriods>element is not significant.
- Initial Version - June 2017
Last updated: June 2017