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:

  • Role-based permission restrictions
  • Idemptpotency
  • Workflows
  • Recipes
  • Deprecated

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:

  • The Name specifies the name of the path parameter.
  • The Type is X. For example, string or int32.
  • The Required flag indicates if the parameter is required. Path parameters are always required.
  • The Description briefly describes the parameter. May specify enum values where appropriate.
  • The Field . If you rollover the Field options may be displayed.

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 Name specifies the name of the query parameter.
  • The Type is X. For example, string or int32.
  • The Required flag indicates if the parameter is required. In general, query parameters are optional.
  • The Description briefly describes the parameter. May specify enum values where appropriate.
  • The Field . If you rollover the Field options may be displayed.

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.

Glossary

  • API
  • app path. The app path is a part in an operation endpoint. The app path identifies the Intelligent Risk Platform application (e.g. riskmodeler, databridge).
  • attribute
  • base path
  • canoncial name
  • client
  • client application
  • Code Builder
  • collection
  • Data Bridge
  • developer documentation. Developer documentation provides developers with instructions about how to effectively use and integrate with an API to build useful applications by means of conceptual overviews, tutorials, sample code, and recipes.
  • Developer Portal
  • endpoint
  • host
  • HTTP header. "HTTP message headers are used to describe a resource, or the behavior of the server or the client. Header fields are kept in an IANA registry. "
  • HTTP request method.
  • HTTP status code. "HTTP response codes indicate whether a specific HTTP request has been successfully completed. Responses are grouped in five classes: informational responses, successful responses, redirections, client errors, and servers errors."
  • Location Intelligence
  • media
  • media type
  • REST
  • RESTful
  • body parameter
  • OpenAPI Specification. "The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic."
  • operation
  • path parameter
  • path
  • query parameter
  • recipe
  • reference documentation. "API documentation is a technical content deliverable, containing instructions about how to effectively use and integrate with an API. It’s a concise reference manual containing all the information required to work with the API, with details about the functions, classes, return types, arguments and more, supported by tutorials and examples."
  • request
  • HTTP request
  • response
  • HTTP response
  • resource
  • Risk Modeler
  • scheme
  • service
  • service path
  • URI
  • version