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
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 would 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 you endpoints would 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 how you need to perform GET and POST methods.
Populating collections
One of the GET endpoints retrieves a collection. This collection can be retrieved using either a Java stream or a Gosu query.
A stream loads the entire collection into memory before manipulating it. Streams have the advantage of being Java objects, which 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, developers who are not familiar with Gosu may find it harder to write complex query logic.
If the collection is likely to be large, Guidewire recommends using a Gosu query. If the collection is not likely to be large, you can choose whichever type of object they prefer to work with.
With Java 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.
Additional considerations
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 had a custom entity named
CustomEntity
. After the REST endpoint generator runs:
- The element resource is named
CustomEntityExt
- The collection resource is named
CustomEntitiesExt
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 attempts to guess the correct plural. If the guess is in correct
(such as guessing CustomChildsExt
instead of
CustomChildrenExt
), you can modify the default.
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 Additional conisderations for generated endpoints.