Viewing API definitions
An API definition is a technical description of the behavior of an API. The API definition typically includes the following:
- The endpoints in the API
- The schemas used by each endpoint, which dictate how resources in the payload are structured
- The fields available in each resource
- The properties that apply to each field
There are several different ways you can view API definitions for Cloud API. This includes:
- Swagger UI
- Calling the
/openapi.json
endpoint (or the/swagger.json
) through a request tool - The Guidewire API references site
Swagger UI
Swagger UI is an open source tool that presents API definitions as interactive web pages. For information on Swagger UI, refer to the Swagger web site: https://swagger.io/tools/swagger-ui/
Swagger UI is automatically bundled with PolicyCenter.
Swagger UI can be helpful when viewing schema information. Swagger UI presents this information hierarchically. Child schemas are indented with respect to parent schemas, and individual nodes of the hierarchy can be expanded and collapsed. Searching through a complex schema is relatively straightforward in Swagger UI.
However, Swagger UI strips out some of the metadata that is present in the source files. For
example, Guidewire-proprietary tags are not rendered in Swagger UI. When you need access to
all the metadata for an API, it may be better to call the /openapi.json
endpoint directly.
Swagger UI also requires access to a running instance of PolicyCenter. If you do not have access to a running instance, you may want to use the Guidewire API References site.
View definitions using Swagger UI
Procedure
- Identify the path for the API. (For a list of paths for each API, see List of APIs in Cloud API.)
- Start PolicyCenter.
-
In a web browser, enter the URL for Swagger UI. This loads the Swagger UI
tool.
- The format of the URL is
<applicationURL>/resources/swagger-ui/
- For example, for a local instance of PolicyCenter, use:
http://localhost:8180/pc/resources/swagger-ui/
- The format of the URL is
-
In the text field at the top of the Swagger UI interface, enter the URL that points to
the desired API's swagger.json file. Then, click Explore.
- The format of the URL is
<applicationURL>/rest<APIpath>/swagger.json
. - For example, to view the common API, enter:
<applicationURL>/rest/common/v1/swagger.json
- The format of the URL is
Results
The following screenshot shows the top of the Swagger UI display of the Common API.
Information in Swagger UI
The Cloud API version number at the top in a gray bubble after the API name. (Note that individual APIs do not have distinct version numbers. The version numbers that appear in Swagger UI are for the entire Cloud API release.)
Every endpoint in the API appears in a list. For each API, the following information is shown by default:
- The endpoint's operation (such as GET)
- The endpoint's path (such as
/activities
) - An endpoint summary (such as "Returns a list of activities assigned to the current user")
If you click the operation button, additional information about the endpoint appears. This includes:
- A more detailed endpoint description
- A list of query parameters supported by the endpoint
- A hierarchical list of resources and schemas used by the endpoint (This appears in the Responses section on the Model tab.)
The API definition endpoints and Postman
In some situations, it is useful to view the raw API definition information. In Cloud API,
every API includes two endpoints that return the API definition:
/openapi.json
and /swagger.json
.
/openapi.json
returns the API definition using the OpenAPI 3.0 specification, often referred to as "OpenAPI 3.0"/swagger.json
returns the API definition using the Swagger 2.0 specification, often referred to as "Swagger 2.0"
/swagger.json
endpoint) or the OpenAPI 3.0 specification (using the
/openapi.json
endpoint).The API definition endpoints can be helpful when you want to view all metadata about an endpoint, including metadata that other tools such as Swagger UI might strip out. However, the API definition endpoints present information in a "raw" format. There is no use of color, font, or placement to help separate information. Schema hierarchies are not as readable as in Swagger UI. When you need to review a schema hierarchy in detail, it may be easier to use Swagger UI.
Retrieving API definitions for these endpoints requires access to a running instance of PolicyCenter. If you do not have access to a running instance, you may want to use the Guidewire API References site.
From a metadata perspective, the OpenAPI 3.0 specification is richer than the Swagger 2.0
specification. So whenever either endpoint is an option, Guidewire recommends using the
/openapi.json
endpoint. For example, Guidewire-proprietary tags (such as
x-gw-typelist
) are listed in the /openapi.json
response,
but not in the /swagger.json
response. However, some tools used to render API
metadata may not be robust enough to process information using the OpenAPI 3.0 specification.
The /swagger.json
endpoint is available for these types of circumstances.
In the base configuration, the API definition endpoints are available to any caller, including unauthenticated callers.
Postman
You can call the API definition endpoints using a request tool. Request tools are not automatically bundled with InsuranceSuite applications. You must download and install them on your own.
Postman is a request tool that Guidewire recommends. This tool has the ability to:
• Save API calls, including headers and payloads
• Save collections of calls
• Automatically create a collection of calls for a schema's paths by importing the Swagger schema file
• Share collections with other developers on your team
For more information and to download the tool, see https://www.postman.com/.
View definitions using Postman
Before you begin
About this task
Procedure
- Identify the path for the API. (For a list of paths for each API, see List of APIs in Cloud API.)
- Start PolicyCenter.
- Start Postman.
- In Postman, start a new request by clicking the + tab to the right of the Launchpad tab.
- Under the Untitled Request label, make sure that GET is selected. (This is the default operation.)
-
In the Enter request URL field, enter the following URL:
<applicationURL>/rest<APIpath>/openapi.json
(or<applicationURL>/rest<APIpath>/swagger.json
). For example, to view the Common API on a local instance of PolicyCenter, enter the following:- http://localhost:8180/pc/rest/common/v1/openapi.json (OR http://localhost:8180/pc/rest/common/v1/swagger.json)
- Click the Send button to the right of the request field.
Results
The API information appears in the results pane. For example, the following is the first part of
the results when calling the previously referenced openapi.json
endpoint:
{
"components": {
"parameters": {
"activityId": {
"description": "The REST identifier for the activity, as returned via previous requests that return a list of activities\n",
"in": "path",
"name": "activityId",
"required": true,
"schema": {
"type": "string"
}
},
...
Information in the output of API definition endpoints
The output of the API definition endpoints is "raw" JSON.
- General information about the API can be found in the
info
section. - The list of endpoints can be found in the
paths
section.- If an endpoint path has multiple operations, the endpoint path is listed only once. Each operation appears under it.
- For example, in the Common API, the
/activities/{activityId}
path has listings for GET and PATCH.
- Summaries and descriptions appear inline with the thing they summarize or describe.
Additional options for the /openapi.json
endpoints
If you are using the /openapi.json
endpoints, the following query
parameters provide additional ways to manage the response. (Note that the
/swagger.json
endpoints do not support the following query
parameters.)
Alternate options for rendering schemas
These query parameters 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.
For example, the following HTTP request retrieves the metadata for the Admin API. It also
enables filterByUser
and prettyPrint
.
http://localhost:8180/pc/rest/admin/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 following query parameter changes 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 contains 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.
For example, the following HTTP request retrieves the metadata for the Admin API. It also disables polymorphism.
http://localhost:8180/pc/rest/admin/v1/openapi.json?enablePolymorphism=false
(For more information on openapi-generator, see https://github.com/OpenAPITools/openapi-generator/.)
The Guidewire API References site
Guidewire Documentation hosts copies of the API references at the following URL:
https://docs.guidewire.com/apiReferences/
This link automatically directs you to the API references of the latest release. From here, you can navigate to the API reference for a specific product and then to a specific API (such as the Admin API).
The API reference information on the Guidewire API References site is based on the output
of the /openapi.json
endpoint. This endpoint returns the API definition
using the OpenAPI 3.0 specification.
The Guidewire API References site is useful when you want to view the API definitions and you do not have immediate access to a working instance of PolicyCenter.
View definitions using the API References site
Procedure
- In a web browser, enter the URL https://docs.guidewire.com/apiReferences/. The site automatically redirects you to the API definitions for the latest version of the product.
- Click the API Reference link under the name of the product, such as PolicyCenter.
- In the left-hand pane, click the name of the desired API.
Information on the API References site
The API reference information on the Guidewire API References site is based on the output
of the /openapi.json
endpoint. This endpoint returns the API definition
using the OpenAPI 3.0 specification.
Every endpoint in the API appears in the left-hand pane. To view information about a specific endpoint, click the endpoint name. This causes information about the endpoint to be shown in the center pane.
The middle pane shows general information about the endpoint, such as:
- The endpoint's operation (such as GET)
- The endpoint's path (such as
/activities
) - An endpoint summary (such as "Returns a list of activities assigned to the current user")
The right pane shows Response samples. You can expand the data.attributes note to see the fields on the parent resource. If there is an included node, you can expand it to see the child resources for the endpoint.