Overview

RMS APIs support query string parameters that provide you with better control over the data returned from a resource. Query string parameters are especially useful in top-level resources that return lists of exposure objects such as lists of accounts, profiles, or treaties.

A query string parameter is a type of REST API parameter that is appended to a resource endpoint. Where the endpoint defines the path to a resource, the query string parameter controls the scope or order of the data returned from that resource.

Use query string parameters to specify a data source to query; and to filter, sort, and paginate the data returned from that data source. The query string parameter is appended to the service endpoint using the ? character.

Synopsis

RMS Risk Modeler supports five basic query string parameters: datasource, q, sort, limit, and offset.

Every query string parameter is defined by a parameter keyword, a query string, and a comparison operator (=) that connects the parameter keyword to the query string. You can use the & operator to append multiple query string parameters to the endpoint.

• A datasource query string parameter defines a filter that specifies the EDM to query.
• A q query string parameter defines an attribute value filter that selects the data returned from a resource. The q keyword supports four filtering operations: comparison operations, logical operations, list operations and matching operations.
• A sort query string parameter specifies an attribute on which to sort and the sort order (alphabetical or numerical) for the records returned from the service. One of ASC for ascending or DESC for descending.
• A limit query string parameter specifies the number of records to display per page. By default, 100.
• An offset query string parameter specifies the number of pages that are offset before the initial page of records returned. By default, 0.

Some Metrics API services enable you to filter and identify relevant analysis results using the exposureId, jobId, jobUUID, perspective, and treatyId query strings.

Data source filters

The datasource query string parameter identifies a specific data source (EDM) to query.

GET /portfolios?datasource=api_edm_3

Many tenants manage their exposure data in multiple EDM data sources. Consequently, the datasource query string parameter is generally required when requesting data from a resource.

Query filters

The q query parameter keyword enables you to define a query string parameter that selects records using attribute value filters and comparison operators. Multiple expressions may be linked together using logical operators.

The q keyword supports four matching operations: comparison, logical, and list operations.

Comparison operators

The q keyword supports comparative queries that return records that match a specified attribute values. These queries support six operators.

The query consists of the q keyword, an attribute, a comparison operator, and a condition that specifies an attribute value. The query compares the value of the specified attribute in each record with the value of the specified condition and selects records that match. Attribute value strings are not case sensitive.

GET /portfolios?datasource=ds1&limit=3&sort=number ASC&q=number LIKE "Portfolio_*"

Risk Modeler supports the = != > < LIKE and NOT LIKEoperators.

• The = operator selects records with attribute values that exactly match a specified attribute value. The = comparison operator may be used to select records attribute values that match strings and numbers.
• The != operator selects records with attribute values that do not match the specified attribute value. The != comparison operator may be used to filter records based on string or number values.
• The > operator selects records with numerical attribute values that are greater than the specified attribute value.
• The < operator selects records with numerical attribute values that are less than than the specified attribute value.
• The LIKE operator selects records with attribute values that match the specified string pattern. The asterisk character (*) may be used as a wildcard character to represent zero or more characters. The LIKE operator may be used to compare strings and numbers.
• The NOT LIKE operator selects records with attribute values that do not match the specified string pattern. The asterisk character (*) may be used as a wildcard character to represent zero or more characters. The NOT LIKE operator may be used to compare strings and numbers.

List operators

The q keyword supports queries that return records that based on values that are or are not is a specified list of attribute values.

• The IN operator selects records with attribute values that match an attribute value specified in a list of attribute values. The IN operator may be used to compare strings and numbers.
• The NOT IN operator selects records with attribute values that do not match an attribute value specified in a list of attribute values. The IN operator may be used to compare strings and numbers.

Logical operators

Some Risk Modeler API services enable you to create complex queries by stringing together multiple attribute value filters using logical operators. The q keyword supports logical queries that return records based on complex queries that compare the value of expresssions.

A logical operator is a keyword that connects two or more expressions to create a compound expression.

GET /portfolios?datasource=ds1&limit=3&sort=number ASC&q=number LIKE "Portfolio_*" AND (description = 1) OR (ownerName ="roland_alphonso")

The Risk Modeler API enables you to create complex expressions using the AND and the OR logical operators:

• In an complex expression using the AND logical operator, both expressions must be true for the complex expression to be true.
• In an complex expression using the OR logical operator, either expression may be true for the complex expression to be true.

Pagination

Sort data

The sort query string parameter enables you to specify the attribute on which returned records are sorted and the sort order (ascending or descending) for those records.

Use the = operator to specify the sort column. In the following example, the returned records are sorted in ascending order based on the attribute value in the number column.

GET /portfolios?datasource=ds1&limit=3&sort=number ASC&q=number LIKE "Portfolio_*"

By default, Risk Modeler API services returns data sorted by a predefined attribute. If no attribute is specified, the service sorts records in ascending order on the default column.

Records may be sorted in ascending (ASC) or descending (DESC) order.

Page data

The limit and offset query string parameters enable you to paginate data returned from a service.

These two query string parameters are always used together. The size of a page will affect the size of the offset. Where the limit query string parameter specifies the number of records returned per page, the offset query string parameter specifies the number of pages that are "off set" before records are returned.

The following request returns records from the ds1 data source, filtered for the year 2018, listed in ascending order, showing 25 records a page starting with page 1:

GET /portfolios?datasource=ds1&q=year=2018&sort=year=ASC&limit=25&offset=1

The default limit setting is 100 records per page. The default offset setting is 0 pages.