Root resource endpoints

Root resource endpoints in Cloud API

Root resources

An endpoint's path consists of an API and a path to a resource element or collection.

For example, given the endpoint path /account/v1/accounts/{accountId}/activities:

/account/v1 is the API
accounts/{accountId}/activities is the path.

The first resource listed in the path is known as the root resource for the endpoint. A root resource is a resource that is identified without any reference to any other resource. When retrieving root resources, you must query the entire database (with or without a query filter).

In the example above, the root resource is account.

For a given endpoint, all resources after the root resource are child resources. A child resource is a resource that is identified with reference to some other resource. When retrieving child resources, you only need to query for child instances related to the appropriate parent.

Generating root resource endpoints for custom entities

In most cases, when you generate endpoints for a custom entity, you want the custom resource to be a child resource. This is because most custom entities are created to extend information about some existing base configuration entity, such as a Claim, Policy, or Account.

For example, suppose an insurer creates a SecurityIssue custom entity that tracks security issues about an account. When generating endpoints for this entity, you would typically have the SecurityIssue resource be a child to the Account resource. The GET endpoints would look like this:

GET /account/v1/accounts/{accountId}/security-issues

GET /account/v1/accounts/{accountId}/security-issues/{security-issue-id}

However, there may be cases where you want to generate endpoints for a custom entity and you want the custom resource to be a root resource. The REST Endpoint Generator supports this use case. If you were to generate endpoints for the SecurityIssue custom entity as a root resource, the GET endpoints would look like this:

```
GET /account/v1/security-issues
```

GET /account/v1/security-issues/{security-issue-id}

Endpoints and foreign keys

For child endpoints for custom entities, the data model entity must have a foreign key to its parent.

For root resource endpoints for custom entities, there are no foreign key requirements. A custom entity can have root resource endpoints, regardless of the presence or absence of foreign keys in the corresponding data model entity.

For example, suppose you had two custom entities: CustomEntity1 has a foreign key to Activity, CustomEntity2 has no foreign keys to any other entities.

For CustomEntity1, you could generate either child endpoints (with Activity as the parent) or root resource endpoints.
For CustomEntity2, you could generate root resource endpoints. But you cannot generate child endpoints.

Advantages to root resource endpoints

You can search for all instances of the resource or retrieve a given instance of the resource without having to first identify the parent.

Disadvantages to root resource endpoints

If the custom entity has a parent in the database, then whenever you create a new instance of the custom entity, you must specify the parent in the payload.

If you want to retrieve all instances of a given resource that are related to a given logical parent, you must add filtering logic to your call to restrict it to only the resource for that parent.

Root resource endpoints are not inherently limited to working with resources for a given parent. Therefore, there is a greater chance that a root resource endpoint can compromise performance by retrieving a large number of resources at one time.

Generating root resource endpoints

One of the first prompts in the REST Endpoint Generator is:

Is the <CustomEntity> entity at the root of the endpoint 
path (GET /activities)? (y = yes; n = no, it is a child 
of some other entity (GET /activities/{activityId}/notes))

To make root resource endpoints for a custom entity, answer this question with y.

For any set of custom endpoints, you have the ability to have the collection backed by a Java stream or a Gosu query. This is determined by the answer to the following question.

Is the collection resource backed by a (s)tream or (q)uery?

Guidewire does not recommend using Java streams with root resource endpoints. Java streams load the entire collection into memory, and root resource endpoints do not limit the collection to those objects associated with a single parent. Therefore, root resource endpoints backed by Java streams may lead to compromised performance.

Configuring root resource endpoints

The REST Endpoint Generator creates and modifies a set of files which require further configuration. Configuration for child endpoints is covered in the following topics:

Configuration of root resource endpoints differs from child resource endpoint configuration in the following ways.

Configuring the collection resource file

The buildBaseQuery method (query-backed collections)

The buildBaseQuery method creates a Gosu query that returns the collection resource related to the parent resource. Root resource entities have no parents. Therefore, in most cases, the query must return all instances of the corresponding data model entity.

The sample code for root resources does this. In most cases, all you will need to do is uncomment the query. For example:

protected override function buildBaseQuery() : IQueryBeanResult<CustomEntity_Ext> { 
                    return Query.make(entity.CustomEntity_Ext).select()

The loadValues method (stream-backed collections)

The loadValues method is used for collections that are backed by a Java stream (and not a Gosu query). Guidewire does not recommend using Java streams with root resource endpoints. Java streams load the entire collection into memory, and root resource endpoints do not limit the collection to those objects associated with a single parent. Therefore, root resource endpoints backed by Java streams may lead to compromised performance.

The createMinimalChild method

The createMinimalChild method is used for POSTs on the collection resource. It creates a new instance of the entity. If the new instance is a child instance, it also attaches it to its parent. Root resource entities have no parents. Therefore, in most cases, this method only needs to return a new instance of the appropriate entity.

The sample code for root resources does this. In most cases, all you will need to do is uncomment the query. For example:

override function createMinimalChildElement(attributes : DataAttributes) : CustomEntity_Ext {
                    return new CustomEntity_Ext()

The canViewException and canCreateException getters

For root resource endpoints, the REST endpoint generator does not generate either a canViewException getter or a canCreateException getter. The purpose of these getters is to determine if an instance of the resource can be viewed or created based on the business state of the parent. A root resource has no parent, and this these getters are not needed.

Configuring the element resource file

The init method

For root resource endpoints, the REST endpoint generator does not generate an init method. The primary purpose of this method is to validate consistency between the new instance and its parent. For a root resource, there is no parent, so there is no consistency to validate.

Configuring resource access for generated files

Resource access determines which instances of a given resource a caller can access. The REST Endpoint generator defaults resource access for root resources in the following ways. It is up to the developer to replace the defaults with more appropriate code as needed.

Note that root resources have no parent, and therefore the __inherit keyword cannot be used for collections.

The following sections detail the default settings for the extension files for some of the base configuration resource access strategies. These settings assume that the custom entity is named CustomEntity_Ext:

internal_ext-1.0.access.yaml

CustomEntitiesExt:
    view: "TODO RestEndpointGenerator"
    create: "TODO RestEndpointGenerator"
  filter: "TODO RestEndpointGenerator"
CustomEntityExt:
  permissions:
    view: __inherit
    edit: "TODO RestEndpointGenerator"
    delete: __inherit

accountholder_ext-1.0.access.yaml

CustomEntitiesExt:
  permissions:
    view: "TODO RestEndpointGenerator"
    create: "TODO RestEndpointGenerator"
  filter: "TODO RestEndpointGenerator"
CustomEntityExt:
  permissions:
    view: "TODO RestEndpointGenerator"
    edit: "TODO RestEndpointGenerator"
    delete: "TODO RestEndpointGenerator"

unauthenticatedUser_ext-1.0.access.yaml

CustomEntitiesExt:
  permissions:
    view: false
    create: false
CustomEntityExt:
  permissions:
    view: false
    edit: false
    delete: false

Root resource endpoint restrictions

There are some entities in the base configuration which are a root resource in one API and a child resource in another. For example:

In ClaimCenter, Activity is a root resource in the Admin API but a child resource in the Claim API.
In PolicyCenter, Activity is a root resource in the Admin API but a child resource in the Account API.

However, for custom resources, the REST Endpoint Generator will generate endpoints only as a root resource or only as a child resource. You cannot run the REST Endpoint Generator twice for the same custom entity to create both root and child endpoints.

There are some entity types, such as custom risk units, that must be a direct or indirect child of Policy. For these types of entities, the REST Endpoint Generator will not allow you to create root resource endpoints. The root resource endpoint prompt is suppressed.

There are some entity types, such as effective-dated entities, that must have a parent. For these types of entities, the REST Endpoint Generator will not allow you to create root resource endpoints. The root resource endpoint prompt is suppressed.