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 payloads are structured
The resources used by each endpoint
The fields available in each resource
The properties that apply to each field

These are the common approaches for viewing API definitions in Cloud API:

Using Swagger UI
Calling the /openapi.json endpoint (or the /swagger.json) through a request tool

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 expended 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.

Note: Be aware that 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. For more information on recommended request tools, see Requests and responses.

View an API definition using Swagger UI

Procedure

Identify the path for the API. (For a list of paths for each API, see The base configuration system APIs.)
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/
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.

Organization of 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 the 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 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.

From a metadata perspective, the OpenAPI 3.0 specification is richer. 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 an API definition 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

Identify the path for the API. (For a list of paths for each API, see The base configuration system APIs.)
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"
                }
            },
...

Organization of 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.