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
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.
Last updated: Dec 2018