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
- In Postman, start a new request by clicking the + to the right of the Launchpad tab.
- Specify Basic Auth authorization using user su and password gw.
- Enter the following call and click Send:
- GET http://localhost:8180/pc/rest/common/v1/typelists/VehicleType
- The response payload contains all non-retired vehicle types. Verify that
the first three codes in the payload are:
Commercial
,PP
,PublicTransport
.) - Modify the call by adding the following query parameter to the end, and
then click Send:
- ?typekeyFilter=category:cn:PolicyLine.PersonalAutoLine
- 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
, andPublicTransport
no longer appear because they are not valid vehicle types for a personal auto policy.)