StatPro Revolution Web API


The Benchmarks Resource


Overview

The Benchmarks resource represents a collection of benchmarks accessible to the logged-in user. Benchmarks in the collection can include system owned ones, those that are owned by the user, and those that are owned by other users and currently shared to the identified user.

Requests for the Benchmarks resource always contain information regarding how the user's benchmarks are to be filtered, ordered and sliced before being returned in a response. Unlike Portfolios or Classifiers, Benchmarks must be filtered to provide a search criteria as there are too many to enumerate system-wide. These instructions may be supplied by the client application (when using a link whose link relation is benchmarks-query), or by the service itself when emitting a non-query link (e.g. a link to the next page of benchmarks).

The underlying collection is first filtered. The filtered set is then ordered. Finally the ordered set is sliced by skipping N benchmarks and taking M benchmarks. If not all of the ordered set is returned in a response, and if N is a multiple of M (e.g. skip 8, take 4), then the benchmarks in the resource representation are paged. A paged collection will include links to the first and last pages, and optionally to the previous and/or next pages.

If no ordering and slicing information is contained in a request, then defaults are used:- ordered by name; take a maximum of 100 portfolios. Note that the web service imposes a maximum 'take limit' of 100 benchmarks for all requests for the resource: it is not possible to retrieve more than 100 benchmarks in any one response.

For more information on filtering, ordering and slicing, refer to the documentation for the benchmarks-query link relation.

The resource representation includes details such as the name, unique identifier, code and owner name of each benchmark.


Media types

The Benchmarks resource is exposed via XML and JSON representations, which have the following media type names:-

application/vnd.statpro.revolution.api.benchmarks+json

application/vnd.statpro.revolution.api.benchmarks+xml

When a response is received from the web service with status 200 (= OK), the fact that the response contains a Benchmarks resource representation is indicated by the presence of one of these two response headers:-

Content-Type: application/vnd.statpro.revolution.api.benchmarks+json; charset=utf-8

Content-Type: application/vnd.statpro.revolution.api.benchmarks+xml; charset=utf-8


Related resources

The Benchmarks resource links to the Service resource. It also links to itself in a variety of different ways. To do so, its resource representations use link relations:-

  • service
  • self
  • first
  • next
  • prev
  • last
  • benchmarks-query

The service link relation identifies the Service resource link.

The self link relation identifies the Benchmarks resource link, in which the representation is the same as the one that has been currently retrieved (so long as the underlying data on the server hasn't changed).

The first and last link relations are present only if the retrieved collection is paged. They identify the first and last pages in the collection (at the time when the resource representation was generated).

The next and prev link relations are present only if the retrieved collection is paged and there is a next page and/or previous page in the collection (at the time when the resource representation was generated).

The benchmarks-query link relation identifies the resource link that allows a fresh query for benchmarks to be made. The fact that the link relation ends with "-query" indicates that a client-specified query must be made for benchmarks, when using this link. This is done by replacing all the text-replacement parts of the link's query string (such as {filter}) with values. Specifying invalid values will result in a 400 (= Bad Request) response. All the text replacement parts of the query string can be replaced with the empty string with the exception of the {filter} query string which must be specified for this link. To apply filtering, ordering and slicing according to a subset of the ODATA system query options syntax, please refer to the benchmarks-query link relation's documentation page.

All related resources are accessed using the HTTP GET method.


Update history

  • Initial Version - December 2016

Annotated Representation (JSON)

Legend

{
  "benchmarks": {
    "links": {
      "service": {
        "rel": "service",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.service+json"
      },
      "self": {
        "rel": "self",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.benchmarks+json"
      },
      "next": {
        "rel": "next",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.benchmarks+json"
      },
      "prev": {
        "rel": "prev",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.benchmarks+json"
      },
      "first": {
        "rel": "first",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.benchmarks+json"
      },
      "last": {
        "rel": "last",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.benchmarks+json"
      },
      "benchmarksQuery": {
        "rel": "benchmarks-query",
        "href": "...?$filter={filter}&$orderby={orderby}&$skip={skip}&$top={top}",
        "type": "application/vnd.statpro.revolution.api.benchmarks+json"
      }
    },
    "filteredCount": 16,
    "pageNumber": 2,
    "pageCount": 4,
    "items": [
      {
        "name": "Benchmark 1",
        "id": "df5e9afb-7725-40a4-996b-3aa65655675e",
        "code": "BM1",
        "owner": "Joe Bloggs",
        "description": "Primary benchmark Description",
        "provider": "N/A",
        "currency": "JPY",
        "type": "Constituent",
        "isSystem": false
      },
      {
        "name": "Benchmark 2",
        "id": "ae95e6a2-f403-4258-99ec-cf4c7e53fa55",
        "code": "BM2",
        "owner": "David Bloggs",
        "description": "The description of the second benchmark",
        "provider": "Not Applicable",
        "currency": "USD",
        "type": "TargetAllocation",
        "isSystem": true
      },
      {
        "name": "FTSE 100 Capped 10%",
        "id": "e61f4e42-a6bd-4318-b18c-ba663d8b4fb8",
        "code": "C0UK",
        "owner": "System",
        "description": "FTSE 100 Capped 10%",
        "provider": "FTSE",
        "currency": "GBP",
        "type": "Total",
        "isSystem": true
      },
      {
        "name": "FTSE 250 ex Investment Trusts",
        "id": "8eb9c712-ea4d-48af-8bc9-77e66969ad3e",
        "code": "MCIX",
        "owner": "System",
        "description": "FTSE 250 ex Investment Trusts",
        "provider": "FTSE",
        "currency": "GBP",
        "type": "Total",
        "isSystem": true
      }
    ]
  }
}


Annotated Representation (XML)

Legend

<?xml version="1.0" encoding="utf-8"?>
<benchmarks xmlns="http://statpro.com/2012/Revolution">
  <link rel="service"
        href="..."
        type="application/vnd.statpro.revolution.api.service+xml" />
  <link rel="self"
        href="..."
        type="application/vnd.statpro.revolution.api.benchmarks+xml" />
  <link rel="next"
        href="..."
        type="application/vnd.statpro.revolution.api.benchmarks+xml" />
  <link rel="prev"
        href="..."
        type="application/vnd.statpro.revolution.api.benchmarks+xml" />
  <link rel="first"
        href="..."
        type="application/vnd.statpro.revolution.api.benchmarks+xml" />
  <link rel="last"
        href="..."
        type="application/vnd.statpro.revolution.api.benchmarks+xml" />
  <link rel="benchmarks-query"
        href="...?$filter={filter}&amp;$orderby={orderby}&amp;$skip={skip}&amp;$top={top}"
        type="application/vnd.statpro.revolution.api.benchmarks+xml" />
  <filteredCount>16</filteredCount>
  <pageNumber>2</pageNumber>
  <pageCount>4</pageCount>
  <benchmark>
    <name>Benchmark 1</name>
    <id>df5e9afb-7725-40a4-996b-3aa65655675e</id>
    <code>BM1</code>
    <owner>Joe Bloggs</owner>
    <description>Primary benchmark Description</description>
    <provider>N/A</provider>
    <currency>JPY</currency>
    <type>Constituent</type>
    <isSystem>false</isSystem>
  </benchmark>
  <benchmark>
    <name>Benchmark 2</name>
    <id>ae95e6a2-f403-4258-99ec-cf4c7e53fa55</id>
    <code>BM2</code>
    <owner>David Bloggs</owner>
    <description>The description of the second benchmark</description>
    <provider>Not Applicable</provider>
    <currency>USD</currency>
    <type>TargetAllocation</type>
    <isSystem>true</isSystem>
  </benchmark>
  <benchmark>
    <name>FTSE 100 Capped 10%</name>
    <id>e61f4e42-a6bd-4318-b18c-ba663d8b4fb8</id>
    <code>C0UK</code>
    <owner>System</owner>
    <description>FTSE 100 Capped 10%</description>
    <provider>FTSE</provider>
    <currency>GBP</currency>
    <type>Total</type>
    <isSystem>true</isSystem>
  </benchmark>
  <benchmark>
    <name>FTSE 250 ex Investment Trusts</name>
    <id>8eb9c712-ea4d-48af-8bc9-77e66969ad3e</id>
    <code>MCIX</code>
    <owner>System</owner>
    <description>FTSE 250 ex Investment Trusts</description>
    <provider>FTSE</provider>
    <currency>GBP</currency>
    <type>Total</type>
    <isSystem>true</isSystem>
  </benchmark>
</benchmarks>


Last updated: December 2016


To Top