StatPro Revolution Web API


The benchmarks-query Link Relation


Overview

The benchmarks-query link relation identifies a link that targets the Benchmarks resource, which is accessed using the HTTP GET method. In addition, a client application must formulate a query for benchmarks, by specifying how the benchmarks 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 benchmarks 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}

When processing a query for benchmarks, the web service will first filter the user's underlying collection of benchmarks. The filtered set will then be ordered. The ordered set will then be sliced by skipping the first N benchmarks, and then by taking M benchmarks. The resulting collection of benchmarks 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). All of the above can be replaced by the empty string with the exception of the $filter query string which is mandatory; failure to do so will result in a 400 (= Bad Request) response. For all other query strings the empty string will cause the following defaults to be used:-

  • order will be determined by the web service
  • zero benchmarks will be skipped in the ordered set
  • a maximum of 100 benchmarks will be taken from the ordered set.

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 Benchmarks resource for more details.


Benchmarks 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 benchmark filtering.

Supported operators and functions:-

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

Supported property names:-

  • Name
  • Code
  • OwnerName
  • Id
  • Provider

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 benchmark ordering.

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

  • Name
  • Code
  • OwnerName
  • Provider

Slicing

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

$top=M indicates how many benchmarks to take from the top of the set of benchmarks 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 benchmark name equals a certain string) is performed case-insensitively.

1) Find an explicitly-named benchmark.

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

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

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

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

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

4) Find benchmarks whose names contain a specified string.

$filter=substringof('ftse', Name)

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

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

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

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

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

$filter=endswith(OwnerName, 'Smith')

8) Order benchmarks by name, ascending.

$orderby=Name
$orderby=Name asc

9) Order benchmarks by owner name, descending.

$orderby=OwnerName desc

10) Skip N benchmarks and take M.

$skip=10
$top=5


Update history

  • Initial Version - December 2016


Last updated: December 2016


To Top