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 straight-forward 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.

Note: Swagger UI also has the capability to send requests to a working endpoint and observe responses. However, Guidewire recommends using Swagger UI only to view API definitions. The APIs in Cloud API are significantly robust. When sending requests using Swagger UI, the performance time for getting responses can be unacceptably long. Also, if you attempt to send calls from Swagger UI and log into the PolicyCenter user interface on the same machine, the two systems may attempt to share the same session, and either or both may stop working. For more information on recommended request tools, see Requests and responses.

View definitions using Swagger UI

Procedure

  1. Identify the path for the API. (For a list of paths for each API, see List of APIs in Cloud API.)
  2. Start PolicyCenter.
  3. 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/
  4. 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

Results

The following screenshot shows the top of the Swagger UI display of the Common API.


User interface for Swagger UI

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"
Note: Cloud API is built using the Swagger 2.0 Specification. However, the definition for each API can be returned in either the Swagger 2.0 specification (using the /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

Install Postman. For more information and to download the tool, see https://www.postman.com/.

About this task

This task does not involve authentication information. This is because every type of caller can request API metadata, including unauthenticated callers.

Procedure

  1. Identify the path for the API. (For a list of paths for each API, see List of APIs in Cloud API.)
  2. Start PolicyCenter.
  3. Start Postman.
  4. In Postman, start a new request by clicking the + tab to the right of the Launchpad tab.
  5. Under the Untitled Request label, make sure that GET is selected. (This is the default operation.)
  6. 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)
  7. 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

  1. 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.
  2. Click the API Reference link under the name of the product, such as PolicyCenter.
  3. 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.