Additional metadata endpoint functionality

Functionality for alternate API tools

Developers using the InsuranceSuite system APIs may want to interact with API metadata using tools other than Swagger UI or Postman. The following functionality may be useful when working with alternate tools. (Note that the /swagger.json endpoints do not support the following query parameters. They are supported only by the /openapi.json endpoints.)

Alternate options for rendering schemas

A query parameter is an expression added to the HTTP request that modifies the default response. The /openapi.json endpoints support the following query parameters, which can be used to change the way in which schema metadata is rendered.

  • filterByUser - Whether to filter endpoints and schema properties by the authorization of this user.
    • Defaults to false
  • prettyPrint - Whether to "pretty-print" the returned schema, making it larger but more human readable.
    • Defaults to false.

To add a query parameters to an HTTP request, use the following syntax:

?<parameterName>=<value>

To add additional query parameters to an HTTP request, use the following syntax for each query parameter after the first:

&<parameterName>=<value>

For example, the following HTTP request retrieves the metadata for the Common API. It also enables filterByUser and prettyPrint.

http://localhost:8180/pc/rest/common/v1/openapi.json?filterByUser=true&prettyPrint=true

Converting schema metadata into SDKs

Some tools, such as openapi-generator, provide the ability to consume a Swagger schema and output a Software Development Kit (SDK). The /openapi.json endpoints support the following query parameter, which can be used to change the way in which an SDK is rendered.

  • enablePolymorphism - Whether to use the discriminator/oneOf pattern to output schemas in cases where the valid set of fields can vary based on some attribute of the data such as the country or subtype.
    • Defaults to true.
    • When set to false, the schema in these cases will contain the superset of all valid fields. For example, address schemas will contain all fields for all countries, rather than have separate schemas for different countries.
    • Setting this to false may make the schema output more consumable by tools that do not support that part of the OpenAPI schema.

To add a query parameters to an HTTP request, use the following syntax:

?<parameterName>=<value>

For example, the following HTTP request retrieves the metadata for the Common API. It also disables polymorphism.

http://localhost:8180/pc/rest/common/v1/openapi.json?enablePolymorphism=false

(For more information on openapi-generator, see https://github.com/OpenAPITools/openapi-generator/.)

The /typelists endpoints

The Common API contains two /typelist endpoints:

  • common/v1/typelists - By default, this returns the names and descriptions of all typelists in PolicyCenter.
  • common/v1/typelists/{typelistName} - By default, this returns the non-retired typecodes in the named typelist.

These endpoints can be useful when a caller application needs to retrieve typecode information from PolicyCenter. In the base configuration, these endpoints are available only to callers who have been authenticated.

Querying with typekey filters

Some typelists have a parent/child relationship. These typelists make use of typekey filters. A typekey filter is a mapping that identifies, for a typecode in one typelist, the valid values in a related typelist. For more information on typekey filters, refer to the Application Guide.

For example, the following typelists make use of typekey filters:

  • ActivityType - The activity's broad type, such as General, Approval, or Assignment Review.
  • ActivityCategory - An activity's specific category, such as Interview, Reminder, or Approval Denied.

If an activity's ActivityType is set to General, then some ActivityCategory values (such as Interview and Reminder) are valid, whereas others (such as Approval Denied) are not.

When using the /typelists/{typelistName} endpoint, if the typelist is associated with a typekey filter, you can use it to limit the response to only the typecodes that are valid when the parent typelist is set to a given typecode. The syntax for this is:

/typelists/{typelistName}?typekeyFilter=category:cn:relatedTypelist.Typecode

where:

  • relatedTypelist is the name of the related typelist.
  • Typecode is the typecode to use as a filter

For example, this call retrieves all typecodes in the ActivityCategory typelist:

GET /common/v1/typelists/ActivityCategory

However, this call retrieves only the typecodes in the ActivityCategory typelist that are valid when ActivityType is General:

GET /common/v1/typelists/ActivityCategory?typekeyFilter=category:cn:ActivityType.general

Including retired typecodes

By default, the common/v1/typelists/{typelistName} endpoint returns only non-retired typecodes. You can include retired typecodes by adding the following query parameter to the call:

?includeRetired=true

Tutorial: Query for typelist metadata

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more information, see Tutorial: Set up your Postman environment.

In this tutorial, you will query for all typecodes in the VehicleType typelist. You will then use a typekey filter to query for all vehicle types that are related to the personal auto policy line.

Tutorial steps

  1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
  2. Specify Basic Auth authorization using user su and password gw.
  3. Enter the following call and click Send:
    • GET http://localhost:8180/pc/rest/common/v1/typelists/VehicleType
  4. The response payload contains all non-retired vehicle types. Verify that the first three codes in the payload are: Commercial, PP, PublicTransport.)
  5. Modify the call by adding the following query parameter to the end, and then click Send:
    • ?typekeyFilter=category:cn:PolicyLine.PersonalAutoLine
  6. The response payload now contains only vehicle types relevant to personal auto policies. Verify that there are only two codes in the payload now: auto, other. (Commercial, PP, and PublicTransport no longer appear because they are not valid vehicle types for a personal auto policy.)