StatPro Revolution Web API


Introduction


Welcome

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.


Join the Developer Partner Program

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

Sample code that shows how to access the Web API is available on GitHub.


Web API Explorer

The StatPro Revolution Web API Explorer website allows you to interactively explore the functionality and capabilities of the Web API. Its source code is available on GitHub.


Address

The address of the web service is:

https://revapi.statpro.com/v1

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.


Stateless access to a user's data

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.


Read-only data access

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.


OAuth2 Authorization

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.


JSON / XML resource representations

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:-

Accept: application/json

To request XML, the Accept request header must be set to:-

Accept: application/xml


(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.)


Chunked transfer encoding

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.


HTTPS-only access

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.


Service structure

The web service is structured as a set of connected resources, as shown in Figure 1 (click the image to enlarge).

Figure 1.  Web service structure

Figure 1. Web service structure

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):

  • The Portfolio Analysis resource contains the portfolio's default portfolio analysis.
  • The Awaiting Sign-Off Portfolio Analysis resource optionally exists if results have been proposed for sign-off. From this resource, analysis results data can be extracted in exactly the same way as from the portfolio's default portfolio analysis resource.
  • The Signed-Off Portfolio Analysis resource optionally exists if results have been signed-off. From this resource, analysis results data can be extracted in exactly the same way as from the portfolio's default portfolio analysis resource.
  • The Compliance Portfolio Analysis resource optionally exists if the portfolio has been activated for Compliance. From this resource, it exposes links to the Compliance Backtesting History and Compliance Validation History resources and, if the compliance analysis has results available, then it in turn exposes links to the Compliance Total Results resource where total level compliance results can be extracted.
  • The Interactive Risk Analysis resource exists if the portfolio is a Platinum portfolio. This resource allows for performing queries for extracting ex-ante risk related results on-the-fly (i.e. unlike other analysis resources which rely on extracting previously calculated results).
  • The Interactive Statistics Analysis resource is always available for all portfolios. This resource allows for performing queries for extracting ex-post risk / performance related statistics on-the-fly.

From the first three of these Portfolio Analysis resources, 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.


Requestable analytics measures

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:-

Accept: application/xml

To request JSON, the Accept request header must be set to:-

Accept: application/json

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.


Response status codes, and error messages + codes

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:-

  • 200 - the entity body will contain the XML or JSON representation of the requested resource.
  • 401 - the Authorization request header is missing or invalid.
  • 400 - the request was badly formed; for example, a query string in the request's URI that should contain a positive integer (in string form) contained a negative integer.
  • 404 - the requested resource couldn't be found.
  • 500 - an unexpected error occurred on the server.
  • 503 - the server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

(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 OK, 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.


Fair Usage Policy

To maintain optimum performance, and to ensure that the StatPro Revolution Web API is available to all our customers, limits are imposed on the usage of the Web API.

Client application authors are required to be aware of the Fair Usage Policy. Applications should be written so as to not violate the policy. Applications must be able to detect when access to the Web API has been blocked because of policy violations.

For full details, please see the Fair Usage Policy page.


Documentation

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.


Getting started

The steps needed to get an application that uses the Web API up and running are as follows:-

  1. Join the Developer Partner Program
  2. Register the application with the StatPro Revolution OAuth2 Server according to the instructions on the Authorization page.
  3. When the application needs to access data from the Web API on behalf of a user, the user must be directed to the StatPro Revolution OAuth2 Server (in a web browser) where he/she will be prompted to allow or deny access to his/her Revolution data, via the Web API, by the application. If allowed, the application completes an OAuth2-based process that provides it with an access token. Full details are given on the Authorization page.
  4. The application requests the Service resource from the Web API's entry-point URI, which is:- https://revapi.statpro.com/v1
  5. For this initial request, and for every subsequent request, the application provides the access token in the Authorization request header. The access token identifies the user who allowed access in step 3, and all data that is returned by the Web API pertains to that user. The application must be prepared to cope with an expired access token, and be able to get a new one. Full details are given on the Authorization page.
  6. An application will typically traverse forwards to the Portfolios resource, using the resource's URI that is given in the Service resource representation that was obtained in step 4. The URI should not be assumed, nor persisted by the application; it may change in the future. Perhaps the application will display all available portfolios in a grid, or perhaps it will query for a particular portfolio.
  7. On selection of a particular portfolio, the application will typically traverse forwards to that portfolio's Portfolio Analysis resource, which contains details of the analysis that has been performed upon the portfolio. Some portfolios may additionally have been activated for Compliance. Such portfolios will expose links to an additional Compliance Portfolio Analysis resource containing details of the settings applied for compliance purposes, as well as indicating status information about the latest results. It is also possible for portfolios to have some results proposed for sign-off or previously signed-off. In this case a portfolio will additionally expose an Awaiting Sign Off Portfolio Analysis resource and/or a Signed Off Portfolio Analysis resource.
  8. If analysis results are available, the service provides links that will allow the application to get (query for) segments, securities, measures, time-series and compliance data from the Segments Tree Node, Whole Segments Tree, Time Series, Multiple OCP Time Series and Compliance Total Results resources.
  9. When the user logs out of or closes the application, the access token (and its associated refresh token) should be discarded.


Last updated: December 2016


To Top