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