API Standards¶

Each API in the Cross Asset Services collection exposes different endpoints depending on the requirements of that business entity and workflow, and there may be some variance in the format of these based on requirements. There are however some standards that each service complies with in order to make using the services as seamless as possible. The following sections outline these standards that apply to the http request and response standards for the API calls.

Versioning¶

When consuming any endpoint from the Cross Asset Service API you can be sure that the contract will never change in a breaking fashion, as we will only ever make backwards compatible changes to an API contract. If a change is required that requires breaking a contract, then a new version of the API will be released so consumers have a choice as to when to upgrade to the new version. Old versions will remain in place and supported for as long as long as required by our SLA.

In order to differentiate the different versions, every URL for an endpoint will begin with a path segment containing the letter v and then a number specifying the version. For example, version 1 of the get all generic deals endpoint in the UAT environment is accessed at https://api.uat.us-cas.ipreo.com/book-building/deals/v1/deals. Where multiple versions of an endpoint exists differences between them will be clearly defined in the documentation.

Search Criteria¶

Many of the API endpoints allow search criteria to be added to the request in order to limit the data that will be retrieved, and these will be clearly identified in the services documentation. There are two different ways that this search criteria may be sent, depending on the http request type; GET requests will include it as a querystring parameter, and POST requests will include it as a form element.

Whichever method is used (and this will be made clear in the service documents), the structure of the parameter is the same and the search works in the same way. An example of the data format is shown below, and then we will describe in detail each element. Only one element is show here, but there can be any number of elements in the array, and these are treated as AND based queries where all the criteria must be met.

Further specific examples of searches will be provided in the individual services documentation.

[
    {
        "field":"string",
        "operator":"string",
        "value":"string"
    }
]

Example : dealServiceUrl/v1/deals/fixed-income/municipal?AccessType=Public&Criteria=[{"field":"lastModifiedTimeStamp","operator":">=","value":"2020-07-14T13:29:51.74593"}]

field

This is the name of the field in the json result that is to be used for the search. For nested properties in complex objects a dot notation is used, like parent.child.grandchild and so on.

operator

The operator is the type of search operation that will be used to compare the search to the actual data. This can be a number of pre-defined operators as shown below:

=	Data value must match the search value exaclty
>	Data value must be greater than the search value
>=	Data value must be greater then or equal to the search value
<	Data value must be less then the search value
<=	Data value must be less then or equal to the search value
IN	Data value must include one or more of the items in the search value

value

The search value that is to be compare to the data value. This is a single value for all operators except IN, where this will be an array of values

Advanced Search Criteria¶

Many of the API endpoints allow search criteria to be added to the request in order to limit the data that will be retrieved, and these will be clearly identified in the services documentation. There are two different ways that this search criteria may be sent, depending on the http request type; GET requests will include it as a querystring parameter, and POST requests will include it as a form element.

Whichever method is used (and this will be made clear in the service documents), the structure of the parameter is the same and the search works in the same way. An example of the data format is shown below, and then we will describe in detail each element.

Further specific examples of searches will be provided in the individual services documentation.

{
    "condition": "or",
    "operands": [
        {
            "field": "field1",
            "operator": "=",
            "value": "value1"
        },
        {
            "field": "field2",
            "operator": "=",
            "value": "value2"
        }
    ]
}

condition

The condition is the logical operator of search operation that will be used to compare the search to the actual data.

and	and condition
or	or condition

operands

This is the list of the criteria that is to be used for the search.

field

This is the name of the field in the json result that is to be used for the search. For nested properties in complex objects a dot notation is used, like parent.child.grandchild and so on.

operator

The operator is the type of search operation that will be used to compare the search to the actual data. This can be a number of pre-defined operators as shown below:

=	Data value must match the search value exaclty
>	Data value must be greater than the search value
>=	Data value must be greater then or equal to the search value
<	Data value must be less then the search value
<=	Data value must be less then or equal to the search value
IN	Data value must include one or more of the items in the search value

value

The search value that is to be compare to the data value. This is a single value for all operators except IN, where this will be an array of values

Pagination¶

In order to protect the services from requests that return large numbers of records, and to make it easier for consumer to implement reasonable pagination levels, many services support server side pagination. Where a service supports pagination will be clearly indicated in the documentation for that specific service. To support pagination, two request parameters are provided; page and pageSize.

Name	Format	Description	Default	Limit
page	integer	Which page of results you wish to retrieve	1	None
pageSize	integer	How many results you wish to retrieve per page	Varies by service	Varies by service

In addition to the request parameters, there is a standard response format which indicates in the results which page these results are for, and the number of records. This JSON response is shown below, along with detailed description of each element.

{
    "total": 0,
    "page": 0,
    "pageSize": 0,
    "items": [
    ]
}

total: The total number of results for the current search, not taking into account any page limits.
page: The page number of the current result set.
pageSize: The size of the current results set, taking into account the page limit.
items: The array of results. The data type of each object will vary depending on the service.

Rate Limiting¶

To protect the services, and to prevent one consumer of a service adversely affecting another, all calls to Cross Asset Services APIs are rate limited. This means that every consumer can make a certain number of calls within a certain time period, and if this is exceeded then further calls are blocked for a period of time. The exact number of calls may vary, and will be specified in the SLA, but will be high enough to allow normal operation of the API and is only in place to protect from accidental or deliberate flooding.

Whenever a call is made to an API, a number of headers are returned with the response to give information on the number of remaining requests. If the number of requests is exceeded, then that request will be blocked and a 429 http response code will be returned. The header details that will be returned are:

X-Rate-Limit-Limit: The time period in which the rate limiting will be applied, in the format <time-value><time-period>. <time-value> is the quantity of time period and is an integer. <time-period> is time period type, and can be s for second, m for minute, or h for hour. For example 30s designates 30 seconds
X-Rate-Limit-Remaining: The number of requests remaining in the current time period.
X-Rate-Limit-Reset: The time in UTC when the limit period is reset.

Character Case¶

In the parameters and consumption of our API’s, we expect that all casing is insensitive.

Your consumption logic and serialization should support Pascal Case, Camel Case, or any combination in between as there is a potential that the character casing may change, and we do not consider this a breaking change.

Sort¶

In order to sort the services, two request parameters are provided; sortField and sortDirection. This is an Array of sort fields, In case of multiple sorts ,it would be treated as “And”

Name	Format	Description	Default	Limit
sortField	string	Field to Sort	None
sortDirection	Asc or desc	Sort Direction	Asc	None

[
    {
        "sortField":"Id",
        "sortDirection":"Asc"
    },
    {
        "sortField":"Name",
        "sortDirection":"Desc"
    }
]