API Reference Documentation

Understand API Reference doc interface

Overview

RMS API Reference documentation offers complete reference documentation of the Risk Modeler, Location Intelligence, and Data Bridge APIs.

API reference documentation provides developers with a "concise reference manual" for using API services including operations and resources. Reference documentation provides detailed information about request parameters and responses with sample code. Our API reference documentation is organized based on the OpenAPI Specification, a standard for defining and documenting RESTful APIs.

API Reference documentation provides detailed information about the nuts and bolts of each operation including the canonical name, endpoint, brief description, parameters (path parameters, query parameters, and body parameters), sample requests and responses.

Reference documentation includes all information needed to build RESTful applications using API operations and resources. API Reference documentation groups services by API (e.g. Risk Modeler, Location Intelligence, and Data Bridge) and collection-- a group of services that operate on the same resource.

An operation (or service) is the combination of an endpoint and a method. Some services share a common endpoint, but different employ distinct methods to operate on a resource made available through that endpoint. For example, the Update account service and Delete account services share the same endpoint (https://{host}/riskmodeler/v2/accounts), but employ different methods (POST and DELETE respectively).

API Reference documentation structure

RMS API reference documentation is displayed in the API Reference tab of the RMS Developer Portal. The Developer Portal provides comprehensive documentation for each operation in a distinct page.

An API reference documentation page is organized into three panels: the API Navigation panel, Operation Details panel, and Code Builder panel:

800800

RMS Developers API Three Panels

Understand how to use each panel:

  • The API Navigation panel enables you to navigate between RMS APIs, API collections, and API operations.
  • The API Operation Details panel displays detailed information about a specific API operation including the endpoint, operation description and parameters.
  • The Code Builder displays sample requests and responses for a specific API operation.

API Navigation panel

The API Navigation panel displays RMS APIs in a tree-like structure that facilitates the navigation between RMS APIs, collections within those APIs, and operations within those collections:

800800

API Navigation panel components

APIs, collections, and operations are nested in a tree-like structure consisting of nodes. You can click an API or Collection node to reveal its contents:

  • API. An API (application programming interface) is a set of tools and protocols that enable software tools and applications to communicate and exchange data. The API exposes services and resources that enable a client application to perform operations. The Developer Portal documents three Intelligent Risk Platform APIs: the Risk Modeler 2.0 API, the Data Bridge API, and the Location Intelligence API.
  • Collection. A collection is a group of operations within an API that work within the same domain . The operations in the collection may belong to the same same API version, mutate the same resource, or support the same business process. For example, the Risk Modeler API includes the the Analysis GroupsV1 and Analysis GroupsV2 collections. These collections contain operations for managing analysis groups for version 1 and version 2 of the Risk Modeler API.
  • Operation. An operation is a callable unit of a REST API. An operation consists of an HTTP method (e.g. GET, POST, DELETE) and a URI that consists of a scheme, host, and path. Operations are identified in the Navigation Panel using the the operation's canonical name. The canonical name typically consists of a verb that identifies the action taken and the name of the resource operated on. For example, the Create account operation enables the client to create an account.

The Navigation Panel also displays a Filter that enables you to "jump to" a collection or operation. The Filter works best if you search for operations using the canonical name.

Operation Details panel

The Operation Detail panel displays detailed information about a single operation.

For each operation, the Operation Detail panel displays its the name of the operation, its endpoint, a brief description of the operation and its purpose, and reference documentation for request parameters and responses:

800800

Operation Details panel components

Understand how to use each panel:

Operation name

The Operation Name section displays the canonical name for a specific service. This canonical name uniquely identifies the service throughout the RMS Develope Portal: in the API Navigation panel, developer documentation and recipes, changelogs, and search results.

Endpoint

The Endpoint section identifies the operation's HTTP request method and unique URI.

The HTTP request method defines X. Usually, one of GET, POST, PUT, PATCH or DELETE, For details, see HTTP request method.

The URI consists consists of a scheme, host, and path:

800800

Data Bridge API operation

  • The host identifies the data center that hosts the tenant's application instance. One of api-euw1.rms.com (Europe) or api-use1.rms.com(United States).
  • The path identifies the unique operation path consisting of the app path, base path, and service path. The app path identifies the Intelligent Risk Platform application (e.g. riskmodeler, databridge. The base path identifies the version of the API (e.g. v1, v2) The service path specifies the path to the service and may include one or more path parameters.

Operation Summary

The Operation Summary section provides a detailed explanation for using a specific service to accomplish tasks as part of standard workflows. A service generally enables the caller to perform an operation on an API resource, the target of of an HTTP request. In general, an RMS API resource corresponds to a schema that defines the structure of data. RMS API services enable clients to manage objects that conform to a resource schema, e.g. creating, updating, and deleting individual accounts.

The operation summary may provide information about: deprecated operations, idemptpotent operations, recipes, role-based permissions, workflows.

Idemptopotent operations

An Idemptpotent Operation admonition identifies an operation as an idempotent operation.

12681268

Workflow jobs

A Workflow Job admonition identifies the workflow job initiated by the operation.

12761276

Role-based permissions

A Permissions operation identifies the Intelligent Risk Platform roles that have permissions to perform a particular operation.

12781278

Recipes

A Recipe admonition identifies a recipe for using an operation to perform a particular task. In general, the recipe identifies related operations and provides a link to developer guide documentation that provides detailed instructions for using the operation in context.

12881288

Deprecated operations

A Deprecated admonition identifies the operation as a deprecated operation.

12821282

Path Params section

The Path Params section provides reference documentation for the operation's path parameters. A path parameter identifies the specific object (e.g. portfolio, location, analysis result) for a request usually by specifying that object's unique ID in the endpoint path.

12361236

Path Params section

Path parameter reference documentation consists of five sections: Name, Type, Required, Description, Field.

Query Params section

The Query Params section provides reference documentation for the operation's query parameters.

Query parameters are generally required or useful for operations that use the GET HTTP method. A query parameter enables the client to filter the data returned by the request in a query string that is appended to the service endpoint.

12201220

Query Params section

The datasource query string is of special note for tenants that make use of multiple EDMs. The parameter identifies the EDM queried. If unspecified, the API assumes that the client application is querying for data in the tenant's primary data source.

For detailed information on how query parameters are employed in Risk Modeler API services, see Query Parameters.

Body Params section

The Body Params section provides reference documentation for the operation's body parameters. A body parameter specifies the value of an object attribute in the body (application/json) of a request to create or update a resource. that resource, so it has to be present in the request body, else the request body would be able to represent the whole resource information.

Responses section

The Responses section documents the responses returned from the API.

The response generally consists of the HTTP response status code and data that is returned in the response body or Location header. In general, successful GET requests return a 200 HTTP status code and data in a request body. Successful POST or PUT service requests frequently return a 201 or 202 HTTP status code and information about the request in the Location header.

RMS Developer Portal provides examples the body parameters for requests in the service descriptions of select operations. Alternatively, the Query Builder provides a GUI for building requests by specifying path, query, and body parameters. As you add new parameters they are added to the endpoint in the sample request.

Query Builder panel

You can view sample request packages by selecting the Request Examples option in the Examples dropdown list.

800800

Query Builder panel

Language section

The Language section enables you to specify a programming language. By default, cURL.

URL section

The URL section identifies the operation's HTTP request method and unique URI.

Query Builder section

The Query Builder section displays a request that has been "built up" using the Reference UI.

  • The Query Builder displays a request in the programming language specified in the Language section.
  • The URL specified in the URL section is automatically added to the Query Builder.
  • Query parameters specified in the Path Params, Query Params, and Body Params sections are automatically added to the Query Builder. the operation's HTTP request method and unique URI.