Beta APIs

Published APIs and endpoints

In future releases, system API functionality is expected to change. To help insurers manage potential future changes, Guidewire maintains a Schema Backwards Compatibility Contract. This document identifies the rules for what Guidewire is allowed to change in an API minor or maintenance release while still having that release considered to be backwards compatible. To request a copy of the Schema Backwards Compatibility Contract, consult your Guidewire representative.

The Schema Backwards Compatibility Contract applies to published APIs and endpoints. These APIs and endpoints have been certified to be stable. By default, schema documentation resources (such as Swagger UI or the /openapi.json endpoints) return only published APIs and endpoints.

Beta APIs and endpoints

Each release of Guidewire Cloud API may include one or more beta APIs or beta endpoints. A beta API and a beta endpoint are an API or endpoint that is not yet covered by the Schema Backwards Compatibility Contract. These APIs and endpoints have not been certified as stable. They may change in the future in ways beyond what is covered by the Schema Backwards Compatibility Contract.

In the base configuration, beta APIs and endpoints:

  • Are not enabled
  • Are not returned by any schema documentation resources (such as Swagger UI or the /openapi.json endpoints)

Guidewire provides beta APIs and endpoints to help insurers with the development of system API functionality that may be available in the future. However, Guidewire recommends using beta APIs and endpoints with caution. They are not certified to be stable, and they are subject to change in future releases.

Warning: Guidewire does not support the use of beta APIs or beta endpoints in production.

Enabling beta APIs and endpoints

Every beta API or endpoint is controlled by a toggle in the config.properties file. A toggle is an expression in config.properties that turns a feature on when the expression is set to true.

For some beta APIs and endpoints, the toggle is listed in config.properties, but it is set to false. For other beta APIs and endpoints, there is no toggle in config.properties. To enable beta APIs and endpoints, you must either set the existing toggle to true, or add a toggle to config.properties and set it to true. After you modify config.properties in this way, you must restart the server.

For example, suppose that a release of Guidewire Cloud API included a fictitious set of beta endpoints that managed insurance metrics. For these endpoints, the following toggle appears in config.properties:

feature.InsuranceMetricsApisBeta = false

To enable these endpoints, you would need to change the line to the following, and then restart the server:

feature.InsuranceMetricsApisBeta = true

Identifying beta APIs

The beta APIs and endpoints for this release, if any, are listed in the following section.

Once enabled, beta APIs and endpoints appear in the output of the /openapi.json and /swagger.json endpoints. All beta APIs endpoints have the following attribute:

"x-gw-beta": true

For beta APIs, the x-gw-beta attribute is listed at the API level. The attribute does not appear at the endpoint level. All endpoints in a beta API are considered beta endpoints.

For beta endpoints in a published API, the x-gw-beta attribute is listed with each endpoint.

The x-gw-beta attribute appears only for APIs and endpoints that are beta. Published APIs and published endpoints do not have a listing of "x-gw-beta": false.

Once enabled, beta APIs also appear in Swagger UI. However, Swagger UI does not indicate whether a given API or endpoint is beta.

Warning: Swagger UI does not render information from Guidewire proprietary tags, including the x-gw-beta tag. This means that, once you enable beta APIs, Swagger UI does not distinguish between published APIs and beta APIs. Guidewire strongly recommends that, if you enable beta APIs on a given development instance, alert all developers using this instance to the fact that beta APIs have been enabled. Without this alert, other developers may not be able to distinguish between published APIs and beta APIs.

Beta APIs for this release

This release contains no APIs that are entirely beta. It also contains no beta endpoints in any of the published APIs.

Guidewire reserves the right to add new beta APIs and endpoints to future releases.