StatPro Revolution Web API


The portfolios-query Link Relation


Overview

The portfolios-query link relation identifies a link that targets the Portfolios resource, which is accessed using the HTTP GET method. In addition, a client application must formulate a query for portfolios, by specifying how the portfolios are to be filtered, ordered and sliced (via query string values in the link's URI).


Notes

A link relation whose name ends with -query indicates that the client application may or must formulate a query (in this case via query strings) before requesting the target resource. A query is formulated by replacing the text-replacement parts of the link's URI (e.g. {filter}) with values before making the request. Failing to replace all the text-replacement parts of the query string, or specifying invalid values, will result in a 400 (= Bad Request) response.

A query for portfolios must specify how the portfolios are to be filtered, ordered and sliced. Accordingly, the link's URI contains the following query strings:-

$filter={filter}
$orderby={orderby}
$skip={skip}
$top={top}
includePublishedPortfolios=
portfolioClassifierCode=

When processing a query for portfolios, the web service will first filter the user's underlying collection of portfolios. The filtered set will then be ordered. The ordered set will then be sliced by skipping the first N portfolios, and then by taking M portfolios. The resulting collection of portfolios is represented by the returned response.

The $filter, $orderby, $skip and $top query strings are all ODATA system query options. Note that the web service only supports a subset of the ODATA filtering and ordering syntaxes. These two subsets are described in the section below.

To formulate a query, replace {filter}, {orderby}, {skip} and {top} in the URI with the correct values. (Filtering and ordering values typically contain spaces, which must be URI-encoded as %20.) The includePublishedPortfolios query string acts as an additional filter and can be specified as 'true' to indicate that all portfolios should be retrieved (excluding portfolios filtered out using the {filter} placeholder) or 'false' to indicate that only portfolios shared to the user with more than publish rights are returned (See the section on Portfolio Accessibility for further details of portfolio permission levels). All of the above can be replaced by the empty string, which will cause defaults to be used; the defaults are:-

  • no filtering
  • order will be determined by the web service
  • zero portfolios will be skipped in the ordered set
  • a maximum of 100 portfolios will be taken from the ordered set.
  • Do not include portfolios shared with publish rights

If no ordering is specified by the client, the web service will impose its own ordering (= by name, ascending).

Certain values for the slicing query options ($skip and $top) may cause the returned collection to be paged. See the documentation for the Portfolios resource for more details.


Portfolios Query Syntax

Filtering

The OData $filter system query option has a complex expression language, with a large set of operators and functions. The Revolution Web API currently supports only a very limited - but still useful - subset of this expression language for portfolio filtering.

Supported operators and functions:-

  • eq operator
  • not operator
  • substringof function
  • startswith function
  • endswith function

Supported property names:-

  • Name
  • Code
  • OwnerName
  • Id
  • InvestmentRegion
  • InvestmentStrategy
  • PortfolioClassificationName

If the property name 'PortfolioClassificationName' is specified, then the portfolioClassifierCode query string must be set to the code of a classifier. The list of portfolio classifiers can be obtained from the classifiers resource by filtering for classifiers where the 'type' property equals 'Portfolio'. Attempts to use a non-portfolio classifier will raise error 870 'ClassifierNotFound'. See the documentation for the Classifiers resource for more details.

(For the Id property, the constraints are that only the eq operator is supported, and the literal string that is equated with the Id property must represent a GUID.)

See below for examples.

Ordering

The OData $orderby system query option has a sophisticated expression syntax for expressing ordering. The Revolution Web API currently supports a limited but useful subset of this syntax for portfolio ordering.

The supported subset takes the form: <propertyName>[ asc|desc] where the property name can be one of:-

  • Name
  • Code
  • OwnerName

Slicing

$skip=N indicates how many portfolios to skip in the set of portfolios that results after filtering and ordering.

$top=M indicates how many portfolios to take from the top of the set of portfolios that results after filtering, ordering and skipping.


Querying Examples

In these examples, query string values are shown with spaces, for clarity. In the actual URIs, the space character must be URI-encoded as %20.

Note that all string matching (e.g. if a portfolio name equals a certain string) is performed case-insensitively.

1) Find an explicitly-named portfolio.

$filter=Name eq 'FTSE 100'
$filter=Name eq 'Equity'

2) Find all portfolios except for the explicitly-named one.

$filter=not (Name eq 'FTSE 100')

3) Find a portfolio by unique identifer (note: only the eq operator can be used in conjunction with the Id property).

$filter=Id eq '792e1752-aedc-4145-90ef-fcd9dec7abd4'

4) Find portfolios whose names contain a specified string.

$filter=substringof('ftse', Name)

5) Find portfolios whose names don't contain a specified string.

$filter=not substringof('ftse', Name)

6) Find portfolios whose codes start with a specified string.

$filter=startswith(Code, 'P')
$filter=startswith(Code, 'FT')

7) Find portfolios whose owner names end with a specified string.

$filter=endswith(OwnerName, 'Smith')

8) Order portfolios by name, ascending.

$orderby=Name
$orderby=Name asc

9) Order portfolios by owner name, descending.

$orderby=OwnerName desc

10) Skip N portfolios and take M.

$skip=10
$top=5


Update history

  • Added support for the new PortfolioClassificationName property - October 2016
  • Added support for the new portfolioClassifierCode query string - October 2016
  • Added support for the new includePublishedPortfolios query string - December 2014
  • Updated the OData website links - September 2014
  • Initial Version - February 2013


Last updated: November 2016


To Top