The REST endpoint generator

The REST endpoint generator is a tool that insurers can use to create a set of generated endpoints for a data model entity that does not have endpoints. This could be either a custom entity, or a base configuration entity for which there are no endpoints. The tool generates a series of files that define the majority of the functionality for the endpoints. However, the insurer must complete some additional configuration.

REST endpoint generator overview

Insurers typically extend the data model of an InsuranceSuite application with new entities specific to their business model. These data model entities are referred to as custom entities.

There may also be entities in the base configuration which have no endpoints, but the insurer wants to expose information in these entities to Cloud API.

Insurers may want to expose these entities to Cloud API so that caller applications can:

  • Retrieve data stored in these entities.
  • Create new instances of these entities.
  • Modify or delete these entities as needed.

To address this need, Cloud API includes the REST endpoint generator. It is a tool that generates a set of CRUD endpoints for an entity that does not have CRUD endpoints.

Architecture and the REST endpoint generator

When you run the REST endpoint generator for a given entity, the tool creates or modifies the files needed to support CRUD endpoints for the entity. The following diagram summarizes the files that are created or modified when running the tool for an entity whose name is CustomEntity_Ext.


Files that define CRUD endpoint architecture for CustomEntity_Ext

Note the following conventions:

  • <API> refers to the name of the API in which the endpoints have been placed.
  • The data model entity file (CustomEntity_Ext.eti) appears in orange because it is not created or modified by the REST endpoint generator. It must exist before the generator is run.
  • The swagger file (<API>_ext-1.0.swagger.yaml) appears in brown because it is modified by the REST endpoint generator, but further configuration is not required.
  • The remaining files, which appear in blue, are created or modified by the REST endpoint generator. Further configuration to these files is either required or recommended.

REST endpoint generator restrictions

The REST endpoint generator can be used only on entities that do not yet have endpoints. This includes:

  • Custom entities for which you have not yet generated endpoints
  • Base configuration entities that do not have endpoints in the base configuration

Note that, for some base configuration entities without endpoints, the REST endpoint generator will prevent you from generating endpoints.

When generating resources, if the entity does not have an "_Ext" suffix, the REST endpoint generator appends an "Ext" or "ext" suffix to the name of the resource in file names and file contents. This is done for both custom entities and base configuration entities without endpoints. It is done to prevent conflicts between insurer configurations and future enhancements of Cloud API.

The REST endpoint generator generates CRUD endpoints only. It cannot be used to create business action POSTs, such as an /assign or /submit endpoint.

Process for generating CRUD endpoints for an entity

To generate CRUD endpoints for an entity, you must do the following:

  1. Run the REST endpoint generator
    • Initially, the tool provides a series of prompts. The answers determine how the endpoints are defined.
    • Once all prompts have been answered, the tool generates and modifies files as needed. To help identify where configuration is needed, the tool adds "TODO RestEndpointGenerator" comments to files needing configuration.
  2. Configure the files that define the resource. This may include any or all of the following:
    1. The swagger file
    2. The schema file
    3. The mapping file
    4. The updater file
  3. Configure the glue and impl Gosu files. This includes:
    1. The apiconfig.yaml file.
    2. The element Resource file.
    3. The collection Resource file.
  4. Configure the authorization files. This includes:
    1. The associated role.yaml files.
    2. The associated access.yaml files.
The following topics describe each of these steps in detail.

Special use cases

Integration graphs

An integration graph is a data model graph used by Guidewire App Events. It defines a set of business information to be sent to an external application as part of outbound integrations. For example, the Claim graph defines what information to send about a claim. For more information on integration graphs, see the App Events Guide.

When you generate endpoints for a custom entity, you can also add the custom entity's resource to an integration graph if the resource has a parent resource and that parent resource belongs to the integration graph. For more information, see Additional considerations for generated endpoints.

Base configuration entities

In most cases, you can generate endpoints for base configuration entities that do not have endpoints. In this case, there are some minor differences in the REST endpoint generator behavior. For more information, see Base configuration entities.

Subtyped entities

You can generate endpoints for a custom entity with subtypes. When you do, you can choose either "shared" or "separate" endpoints.

  • You can generate "shared" endpoints, which may be appropriate when the majority of the information is declared at the supertype level. In this case, the resource has the supertype fields and the subtype fields from each subtype.
  • You can generate "separate" endpoints, which may be appropriate when there is a sufficient amount of information at each subtype level. In this case, the resource has only the supertype fields. Subtype fields are omitted. To access information at the subtype level, you must re-run the REST endpoint generator for each subtype.

For information on generating endpoints for subtyped entities, see Additional considerations for generated endpoints.

Root resources

In most cases, when you generate endpoints for a custom entity, the custom entity is child to some existing parent entity. You access the associated REST resource through that parent resource.

For example, suppose you have a custom entity named CustomEntity_Ext. It is a child of the existing Activity entity. Information about CustomEntity_Ext instances are accessed through the parent Activity. In this case, the endpoints have this structure:

  • GET /common/v1/activities/{activityId}/custom-entity-ext
  • GET /common/v1/activities/{activityId}/custom-entity-ext/{CustomEntityExtID}

However, it is possible to generate endpoints for a custom entity as a root resource. In this case, you access the associated REST resource directly.

For example, suppose you have a custom entity named CustomEntity_Ext. The endpoints are generated with the associated resource being a root resource. In this case, the endpoints have this structure:

  • GET /common/v1/custom-entity-ext
  • GET /common/v1/custom-entity-ext/{CustomEntityExtID}

For more information on generating endpoints for root resources, see Additional considerations for generated endpoints.