StatPro Revolution Web API
- Advisory for .NET client applications re. 'authenticating proxy servers'
- Maximum URI Length
- Handling Transient Errors
- How to display measure names correctly
- Client-defined resource pagination via $skip and $top OData system query options
Advisory for .NET client applications re. 'authenticating proxy servers'
Client applications that run on Microsoft's .NET Framework may encounter problems when trying to talk to the Revolution Web API and OAuth2 Server if an authenticating proxy server sits between the application and web. This is of particular concern for desktop applications that are widely distributed, and installed by different organizations. In most cases there should be no such connection problems, but some specific environments where an authenticating proxy server is used may encounter problems.
The easiest way to deal with this problem is build your application from the outset with an App.config file (Web.config for ASP.NET web applications) with the following configuration:-
<system.net> <defaultProxy useDefaultCredentials="true" /> </system.net>
This configuration sits inside the top level
configuration element, and is usually placed at the bottom:-
<configuration> <!-- other config --> <system.net> <defaultProxy useDefaultCredentials="true" /> </system.net> </configuration>
If your config file already has a
<system.net>...</system.net> section, then the
defaultProxy element should be placed inside it.
For further information, please see:- http://stackoverflow.com/a/8180854/98689
Maximum URI Length
URIs that target the Revolution Web API's resources can have a maximum length of 4096 characters. Attempts to get resources using longer URIs (for example those that request a very large number of measures from the Segments Tree Node resource) will normally result in
404 Not Found being returned as the response status code and reason phrase.
For example, if a very large number of measures is requested from the Segments Tree via the StatPro Revolution Web API Explorer website, such that the resulting Web API URI exceeds 4096 characters, the Explorer will display the error message it received from the Web API:- "Not Found".
Handling Transient Errors
Client applications should be written so as to correctly identify and respond to transient Web API errors (see table below). Transient errors (e.g. Timeouts) are generally temporary. Client applications should therefore handle such errors by logging the error details and re-trying a number of times. If the retry attempts fail, prompt the user to re-try later. When retrying, an exponential back-off strategy should be employed, i.e. increasing the wait period; e.g. 5 seconds, 10 seconds, 20 seconds. A longer wait period of a minute is recommended for Interactive Risk in the case of a Timeout (853) error. When logging the error, please include the UTC time, HTTP status code, reason phrase, requested URI and POST data). StatPro monitors the frequency of transient errors, and strives to ensure that they are minimized.
Table of transient errors:
|HTTP Status Code||Category||Notes|
|503||Service Unavailable||A timeout is triggered by an attempt to get a resource in response to a client request, but the attempt takes longer than thirty (30) seconds.
The reason phrase may have an optional Revolution Error Code suffix, for example: "(REVAPI_ERROR=853)" for a Timeout, or "(REVAPI_ERROR=915)" for an UnexpectedTransientError.
Example: When a timeout is triggered, the Web API responds with HTTP status code 503 and reason phrase:
The server took too long to respond. Please try again later. (REVAPI_ERROR=853)
How to display measure names correctly
Web API resources that provide measures and their values (from the segments tree or from a time series) identify the measures by providing their identifiers (e.g. "WOver").
To map these identifiers to their corresponding measure names, a client application should acquire the Segments Tree measures, Time Series measures and Interactive Risk measures lists in XML or JSON form. By default, these three URLs return the measures info lists in HTML form. To request XML, the Accept request header must be set to:-
To request JSON, the Accept request header must be set to:-
Note that the XML and JSON formats are so simple as to be self-explanatory. Note also that a client application does not need to supply a bearer access token when requesting these two lists.
Armed with these two lists, a client application can easily map a measure's identifier to its name; e.g. "WOver" -> "Excess Weight Mean".
Some measure names contain "[CUR]", "[SUBPERIOD]" and "[SUBPERIODS]". Examples are:-
- Return ([CUR])
- Relative Return ([SUBPERIOD] Average)
- Recovery [SUBPERIODS] after Max Loss
These measure names are not intended to be displayed to the end user as-is. Instead, "[CUR]" should be replaced with the portfolio analysis's currency code. This is an ISO 4217 currency code; an example is "GBP". "[SUBPERIOD]" should be replaced by the portfolio analysis's statistics frequency, which will be one of: "Weekly", "Monthly" or "Quarterly". "[SUBPERIODS]" should be replaced by the portfolio analysis's statistics frequency, followed by " Returns".
The portfolio analysis that provides this data is the finished default portfolio analysis that links to the Segments Tree or Time Series resource that provided the measures in question. The currency code is provided by the analysis's "currency" member/element, and the statistics frequency is provided by the "statisticsFrequency" member/element. See the Portfolio Analysis resource for details.
So, for a finished portfolio analysis whose currency is "GBP" and statistics frequency is "Weekly", and for measures included in results resources that are linked to by this analysis, instances of "[CUR]" in the names of the measures should be replaced by "GBP". Instances of "[SUBPERIOD]" should be replaced by "Weekly". Instances of [SUBPERIODS] should be replaced by "Weekly Returns". Following on from the example measure names above, this gives:-
- Return (GBP)
- Relative Return (Weekly Average)
- Recovery Weekly Returns after Max Loss
- Time Series and Interactive Risk Analysis compatible measures do not include "[SUBPERIOD]" or "[SUBPERIODS]" in their names.
- The source code of the Web API Explorer application on GitHub illustrates the techniques described above.
Client-defined resource pagination via $skip and $top OData system query options
Queries for the following resources support paging:-
- Risk Free Rates
- Segments Tree Node (a node's child segments or securities can be paged).
For example, a thousand portfolios will not be contained in one Portfolios resource representation. Rather, they will be spread out over a number of different 'pages' of this resource.
It is important to note that the paging - in terms of the page size and thus the total page count - is client-defined and not server-defined.
The server (i.e. the Web API) does not say, for example: "each page always has 50 items, except for the last page which may have fewer". If it did, then we could confidently predict that 103 portfolios would be divided over 3 pages: 50 + 50 + 3.
Rather, paging is defined by the client application, via the values it specifies for the
$top OData system query options. Here's an example:- for 103 portfolios, if
$top=1, this will result in 103 pages, each containing just one portfolio. The Portfolios resource representation for the first page will include a
next link to the second page. The second page will include a link to its next page (and also to the previous page). The links to the 2nd, 3rd, 4th... pages work by incrementing the
$skip value from 0 to 1, 2, 3...
To continue the example, if
$top was originally specified as 20, then this will give a page size of 20. The total number of pages would therefore be 6. The first five pages would have 20 portfolios each, and the sixth page would have the remaining 3.
When the client application doesn't specify values for
$top, the following defaults are used:-
Also note that if a client specifies a
$top value greater than 100, it is rounded down to 100. Thus it follows that the page size can never be greater than 100.
Finally, the following conditions mean a resource is not paged:-
$top= 0 (i.e. take no items)
$skipisn't integer-divisible by
$top=4; to enable paging
$skipmust be 0, 4, 8, 12...)
- there are no items (the resource is empty)
- the total number of items is less than or equal to the page size (i.e. the
When a resource is not paged, the specified
$top values are honoured, but the
last links and the
pageCount fields are absent from the JSON and XML resource representations.
For further details, see the documentation pages for the resources and their link relations. See also the OData system query options.
Last updated: January 2019