Issues to consider before running the generator

The REST endpoint generator asks a series of questions, which determine the behaviors of the endpoints. Some questions have significant implications on this behavior. Guidewire encourages developers to consider the following issues prior to running the generator.

The API for the new endpoints

You must identify which API (such as Common or Admin) to add the endpoints to.

The Job API

Guidewire recommends adding endpoints to the Job API only if the underlying entity is effective-dated. Adding endpoints to the Job API for non-effective-dated entities is not recommended.

When you add endpoints to the Job API, the REST endpoint generator also adds the corresponding GET endpoints to the Policy API. The generator also adds appropriate PolicyCenter-specific query parameters, such as asOfDate and jobVersion, to the endpoints.

Any roles that are given GET access to endpoints in the Job API will also have access to the GET endpoints in the Policy API.

Schemas, mappers, updaters, Swagger parameters, and Swagger request/response envelope definitions are added to the policyperiod files, rather than job or policy files.

The Policy API

You cannot add endpoints directly to the Policy API. The only way to add endpoints to the Policy API is to add them to the Job API. Any GET endpoints added to the Job API are automatically copied to the Policy API.

The Account API, Admin API, and Common API

Endpoints for a custom entity can be added to the Account API, Admin API, or Common API only if the custom resource is not effective-dated.

The Product Definition API

If the entity corresponds to a system data table, it is automatically added to the Product Definition API. This is the only type of custom endpoint you can add to the Product Definition API.

The Composite API, the System Tools API, and the Test Util API

You cannot add custom endpoints to these APIs.

Summary of entity types and APIs

API Add endpoints for effective-dated entities? Add endpoints for non- effective-dated entities?
Account API No Yes
Admin API No Yes
Common API No Yes
Composite API No No
Job API Yes Not recommended
Policy API Yes, but only by adding them to the Job API. Endpoints cannot be added directly to the Policy API. No
Product Definition API No System tables only
System Tools API No No
Test Util API No No

The parent of the custom resource

In most cases, the custom entity is the child of an existing entity (such as a claim or an account). The custom entity may be a direct child of a single parent. But the custom entity could also be part of a hierarchy that is several levels deep. When the custom entity has multiple ancestors, you have a choice in the structure of the endpoint path.

For example, suppose you have a CustomEntity_Ext entity which is the child of AccountContact, and AccountContact is the child of Account. When you generate the endpoints, you can make the custom resource a descendent of its immediate parent (AccountContact), or a distant ancestor (Account).

Choosing the immediate parent

If you choose the immediate parent, then your endpoints look like this:

  • GET /account/{accountId}/contacts/{contactId}/custom-entities-ext
  • POST /account/{accountId}/contacts/{contactId}/custom-entities-ext
  • GET /account/{accountId}/contacts/{contactId}/custom-entities-ext/{customEntityExtId}
  • PATCH /account/{accountId}/contacts/{contactId}/custom-entities-ext/{customEntityExtId}
  • DELETE /account/{accountId}/contacts/{contactId}/custom-entities-ext/{customEntityExtId}

With this approach, you cannot retrieve all CustomEntity_Ext instances for a single Account in one call. You would need to make multiple calls, one for each AccountContact.

When you create a new CustomEntity_Ext, the immediate parent (the AccountContact) is specified in the URL. Therefore, the new resource is linked to its immediate parent.

Choosing a distant ancestor

If you choose a distant ancestor, such as Account, then your endpoints look like this:

  • GET /account/{accountId}/custom-entities-ext
  • POST /account/{accountId}/custom-entities-ext
  • GET /account/{accountId}/custom-entities-ext/{customEntityExtId}
  • PATCH /account/{accountId}/custom-entities-ext/{customEntityExtId}
  • DELETE /account/{accountId}/custom-entities-ext/{customEntityExtId}

With this approach, you can retrieve all CustomEntity_Ext instances for a single Account in one call.

When you create a new CustomEntity_Ext, the immediate parent (the AccountContact) is not specified in the URL. Therefore, the new resource is not automatically linked to its immediate parent. (It may be possible to link the new resource to its immediate parent by explicitly adding it to the request payload.)

Making the choice

From a technical standpoint, either choice is valid. The best choice depends on the types of GETs and POSTs you plan to execute most frequently.

Populating collections

One of the GET endpoints retrieves a collection. This collection can be retrieved using either a stream or a Gosu query.

A stream loads the entire collection into memory before manipulating it. Streams have the advantage of being objects that developers may be more familiar with. Filtering and sorting may be easier with stream-backed resources as the whole collection is loaded into memory. However, streams may degrade performance if the size of the collection is too large.

Gosu queries are expressions that are converted into SQL queries. Queries have a maximum number of elements that are loaded into memory at one time. Queries have the advantage of preserving performance if the size of the entire collection is large, as the collection is loaded in portions. However, if you are not familiar with Gosu, you may find it harder to write complex query logic.

Guidewire has the following recommendations:

  • If the collection is likely to be large, use a Gosu query.
  • Otherwise, use a stream.

With streams, you will need to write code to populate the stream. This is easy to do when the parent entity has an array of custom entities, as the array can be converted into a stream. Therefore, if you decide to use streams, you may want to add an array of custom entities to the parent, even if the application does not otherwise require an array.

External callers (such as insureds or producers) may not have access to third-party data on claims (such as contact and vehicle information related to a vehicle that the insured damaged). For these types of callers, access to specific fields may be restricted by additional accessible fields filters. For fields restricted by additional accessible fields filters, the behavior of sorts and filters changes based on whether the collection is populated by a stream or query. For more information, see Sorting and filtering on accessible fields.

Additional considerations

You must identify the API roles that will have GET, POST, PATCH, and DELETE access to the custom endpoints.

You can add the custom resource to an integration graph. For more information, see Integration graphs.

If the custom entity has subtypes, you can generate either a single set of shared endpoints to work with supertype and subtype behavior simultaneously, or you generate separate sets of shared endpoint that work with each supertype or subtype independently. For more information, see Supertype entities.

Naming conventions during generation

Entity Ext prefix or suffix

The REST endpoint generator expects custom entities to conform to the naming convention of starting or ending with "Ext". (This convention is designed to prevent custom entities from conflicting with base configuration entities added in future releases.) If the custom entity does not start or end with Ext, the REST endpoint generator adds an "ext" suffix to the name. For example, suppose you have a custom entity named CustomEntity. After the REST endpoint generator runs:

  • The element resource is named CustomEntityExt
  • The collection resource is named CustomEntitiesExt

Plural name for resource

The REST endpoint generator provides a default name for the resource collection. Guidewire recommends naming this using the plural form of the custom entity name. The REST endpoint generator guesses the correct plural. If the guess is incorrect (such as guessing CustomChildsExt instead of CustomChildrenExt), you can modify the default.

Hyphenation in paths

The endpoint paths consist of custom entity name converted into lower case letters, numbers, and hyphens. Certain characters or character combinations in the entity name cause the path to be generated in a particular way.

  • Upper-case letters are converted to lower letters. (The path for Inspector_Ext is /inspector-ext.)
  • Underscores are converted to hyphens. (The path for Inspector_Ext is /inspector-ext.)
  • Single capital letters in the middle of the name are preceded with a hyphen. (The path for SecuritySystem_Ext is /security-system-ext.)
  • If the entity name contains multiple capital letters in a row (such as BOPLine_Ext), the REST endpoint generator guesses at the correct way to apply hyphenation (such as /bop-line-ext). If the guess is incorrect (such as being given USBOPLine_Ext and guessing /usbop-line-ext instead of /us-bop-line), you can modify the default.

Effective-dated entities

Guidewire recommends added only effective-dated entities to the Job API. Effective-dated entities use the PolicyCenter-specific EffDatedRestElementResource and EffDatedRestListCollectionResource classes.

When you generate endpoints for an effective-dated entity, the following prompts are suppressed:

  • The prompt asking if the resource is a root resource or a child resource.
    • Effective-dated entities must be child to an existing parent resource.
  • The prompt asking if the collection resource is backed by a stream or a query.
    • Effective-dated entities are always assumed to be stream-backed resources.
  • The prompt asking if the resource is to be added to an integration graph.
    • Effective-dated entities are always added to the policyperiod graph.

System tables

If an entity is a system table, the REST endpoints generator automatically creates a single GET collection endpoint. The endpoint is a root resource endpoint in the Product Definition API, and its path starts with /reference-data.

When you generate endpoints for system tables, the following prompts are suppressed:

  • The prompt asking which API to create the endpoint in.
    • System table endpoints are always created in the Product Definition API.
  • The prompt asking if the resource is a root resource or a child resource.
    • System table endpoints are always root resource endpoints.
  • The prompt asking if the collection resource is backed by a stream or a query.
    • System table endpoints are always query-backed resources.
  • The prompt asking if the resource is to be added to an integration graph.
    • System table resources cannot be added to any graph.