Welcome to the StatPro Revolution Web API - an HTTPS-based web service that allows developers to write applications that access StatPro Revolution’s data programmatically, over the web.
The following sections will help you get started with the Web API. Note that the terms “web service” and “Web API” are used interchangeably.
Please register your interest in learning about the Web API, and in developing an application that uses it, by joining the Developer Partner Program.
This is currently the only way to receive certain important updates regarding the Web API and related services and technologies.
Sample code that shows how to access the Web API is available on GitHub.
The address of the web service is:
This is the only address/URI that you need to know. It is known as the bookmark URI, also as the entry-point URI.
All other URIs (which identify the web service’s various resources) are returned dynamically by the service. These URIs should not be hard-coded into an application, nor stored in long-term storage. These URIs may change over time; the entry-point URI will never change.
Each and every request to the web service must identify a Revolution user. The data contained in the response pertains to that user only. The web service is stateless - there is no user session.
The Web API affords read-only access to the same data that is displayed and operated upon in the main Revolution website. Changes in the latter are reflected in the data that is supplied by the Web API.
Web API uses the OAuth 2.0 Authorization Framework for user-authorized access to resources. To enable this, client applications must be registered with and talk to the StatPro Revolution OAuth2 Server. The OAuth2 Server gets a user’s permission for a client application to access his/her data via Web API, and then provides the application with an access token. The application includes the access token in each and every request to Web API.
The OAuth2 Server is compliant with the final, published specification of the OAuth 2.0 Authorization Framework. Web API is compliant with the final, published specification for OAuth 2.0’s Bearer Access Tokens.
Full details of registering a client application with the OAuth2 Server, getting an access token, and passing the access token to Web API are given on the Authorization page.
Requests are made from client to server for resources, and the server responds with representations of those resources. The web service supports both JSON-based and XML-based representations, constructed according to its own schemas.
To request JSON, the Accept request header may be omitted, or set to:-
To request XML, the Accept request header must be set to:-
(In exceptional cases, a resource will represent its data in a format other than JSON and XML. Currently the Whole Segments Tree resource is the only one to do this. It exposes only CSV (comma-separated values) data, and ignores the contents of the Accept request header.)
The Web API sends responses using HTTP’s Chunked Transfer Encoding. Clients must be able to decode this encoding in order to fully and correctly receive responses from the web service.
The Revolution Web API can only be accessed over HTTPS. Thus the entry-point URI and the URIs to resources that the Web API emits are all HTTPS-based. If an attempt is made to access the web service over HTTP, then typically a 403 response status code will be returned.
Note that some web frameworks for constructing client applications may require special configuration (e.g. installation of a particular module) before they can issue requests over HTTPS.
The web service is structured as a set of connected resources, as shown in Figure 1 (click the image to enlarge).
The entry-point URI (see above) identifies the Service resource, on the top in Figure 1. When requested, the Web API returns a representation of this resource (in either XML or JSON format) to the client application. This resource contains a link to the (collection of) Portfolios resource. It also contains links to other resources such as Benchmarks, Classifiers and Risk Free Rates but most of the analytics is extracted from beneath the Portfolios resource.
Continuing forwards from the Service resource, a client app typically queries for one or more portfolios in the Portfolios resource. Selecting one of the portfolios, a client app typically requests one of the many types of Portfolio Analysis resources (via a service-supplied link). A Portfolio can expose one of the following portfolio analysis resources depending on the configuration of each portfolio (See the documentation of each resource for further details):
From the first three of these kinds of Portfolio Analysis resource, a client app follows links to access analysis results data in the form of segments, measures, securities and time-series data in the Segments Tree Node, Whole Segments Tree, Time Series and Multiple OCP Time Series resources, and may obtain history risk figures via the Liquidity Risk History and Historical Risk Trends resources.
Analytical measures are requestable from analysis results data, via the Segments Tree Node, Whole Segments Tree, Time Series, Multiple OCP Time Series, Interactive Risk Analysis and Interactive Statistics Analysis resources.
Measures are divided into four categories, Segments Tree measures, Time Series, Interactive Risk Analysis measures and Interactive Statistics Analysis measures:-
By default, the above URLs return the measures info lists in HTML form. The lists can also be provided in XML and JSON form. To request XML, the Accept request header must be set to:-
To request JSON, the Accept request header must be set to:-
The XML and JSON formats are so simple as to be self-explanatory. Note that the measures info list for Time Series includes a flag that says whether each measure is compoundable or not.
A client application can receive responses from the Revolution Web API itself, from the web server software that hosts it (on the origin server) and from any HTTP intermediaries that happen to sit between the client app and the origin server. Thus a client app should be prepared to deal with any/all HTTP response status codes.
The Web API itself typically returns the following response status codes:-
(The above list is not exhaustive; the Web API may return other status codes.)
After the status code on the status line in the response is a space, followed by the reason phrase. This may be one of the standard reason phrases, such as
Not Found and
Internal Server Error. In the case of status codes in the 4xx and 5xx range, the Web API may return a reason phrase in the following form:-
<error message>: (REVAPI_ERROR=<error code>)
An example is:-
The specified portfolio doesn't exist, or isn't available to the identified user. (REVAPI_ERROR=839)
To determine if the reason phrase contains such as an error, search for “ (REVAPI_ERROR=“. The error code is specific to the Revolution Web API; the complete list of error codes and error messages is given in Appendix 1 - Error Codes.
To maintain optimum performance, and to ensure that the StatPro Revolution Web API is available to all our customers, limits may be imposed on the usage of the Web API.
For further details, please see the Fair Usage Policy page.
The StatPro Revolution Web API is primarily described in this documentation in terms of its resources, media types and link relations. The media types describe each resource’s representations (XML and JSON, or CSV), and the link relations describe the semantics of the service-supplied links that connect resources.
It is important to understand each media type and link relation. Fortunately you can take each media type (and its associated link relations) one resource at a time, working from left to right in Figure 1 above. This mirrors how your application will work: on startup it will always enter at the entry-point URI, and there it will progress from left to right.
The steps needed to get an application that uses the Web API up and running are as follows:-
Last updated: December 2017