Overview of resource definition files

Within the context of REST, a resource is a collection of data that is part of either a REST request or a REST response. For example, when you create an activity through a REST endpoint:

  • The request includes a resource that specifies information about the activity to be created (such as the activity's subject and due date).
  • The response includes a resource that specifies information about the activity that was created (such as the activity's subject and due date, as well as information created by the application, such as the activity's ID and status.)

Within Cloud API, every resource is defined in up to there are three files:

  • The schema file, which defines the structure of the schema used by element and collection resources.
  • The mapping file, which defines how information is mapped from the data model entity to the element resource.
    • This information is used for GETs, and for the responses of POSTs and PATCHes.
  • The updater file, which defines how information is mapped from the element resource to the data model entity.
    • This information is used for POSTs and PATCHes.

There are two other files which are related to schema functionality.

  • The swagger file, which defines the endpoints themselves. The definition of each endpoint includes:
    • The endpoint path (such as /common/v1/activities/{activityId})
    • The operations allowed on the path (such as GET or PATCH)
    • The resourceType of the endpoint (such as Activity) and any associated child resources.
  • The apiconfig file, which defines the default sort, if any, for resource collections.

Resource definition file architecture

The following diagram depicts the resource definition file architecture for the Activity data model entity.


Architecture of resource definition files
  • The Activity.eti file defines the Activity data model entity. Note that this file is part of the data model and not a part of Cloud API.
  • The schema file defines two resources that can be used by Cloud API to interact with Activity data model objects:
    1. The Activity resource, for capturing information about a single resource.
    2. The Activities resource, for capturing information about a collection of resources.
  • The mapping file defines how data is mapped from the Activity data model entity to the Activity resource.
  • The updater file defines how data is mapped from the Activity resource to the Activity data model entity.
  • The swagger file defines the CRUD operations for the endpoint. It associates an endpoint (such as /common/v1/activities/{activityId}) to its root resource (the Activity resource).
  • The apiconfig file defines the default sort order for the Activities collection resource.

All of the schema files conform to the Swagger 2 specification. For syntax details, refer to https://swagger.io/specification/v2/.

The schema, mapping, and updater files are in JSON format using JSON Schema syntax. For details on JSON Schema syntax, refer to http://json-schema.org/.

Reasons to modify resource definition files

Generating endpoints for custom entities

The REST endpoint generator is a tool that generates CRUD endpoints for custom data model entities. The REST endpoint generator also creates schema definition files for the resources used by the generated endpoints. However, these files are incomplete. Developers must always execute additional configuration in the resource definition files.

For more information on the REST endpoint generator, see The REST endpoint generator.

Extending base configuration resources

Cloud API has endpoints that perform CRUD operations on several data model entities in the base configuration. For example, the GET /common/v1/activities endpoint queries for instances of the Activity data model entity. Insurers can extend these data model entities by adding custom fields. Insurers may also want to expose these fields to the REST endpoints. Insurers can configure schema definition files to add custom resource properties that map to custom data model fields.

To extend a base configuration schema:

  1. If necessary, extend the underlying data model entity with new fields.
    1. For more information, see the Configuration Guide: Configuration Guide.
  2. Configure the appropriate schema, mapping, and updater extension file.
    1. For more information, see Data mapping for new properties
  3. Add attributes to define additional property behaviors, if necessary.
    1. For more information, see Additional behaviors for properties

Exposing base configuration fields to Cloud API

For the data model entities that are exposed in Cloud API, the base configuration does not expose every field in a given entity to Cloud API. There may be situations where you need to expose one or more of these fields to Cloud API.

For example, the User data model entity is exposed to Cloud API. The VacationStatus field is also exposed. But, the ExperienceLevel field is not. An insurer may want to expose the ExperienceLevel field to Cloud API.

The approach for doing this follows the same process as extending a base configuration resource. The only difference is that there is no need to extend the data model as the field in question already exists.

Integration graphs

Cloud API schemas are used to define the integration graphs used by Guidewire App Events . An integration graph is a data model graph that 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. Insurers may want to extend Cloud API schemas to ensure that certain information is included in the integration graph. For more information on integration graphs, see the App Events Guide.