The resource definition files

The schema, mapping, and updater files

For a given Cloud API resource, there are three files that define the structure of the resource and how it connects to the corresponding data model entity:

The schema file, which defines the schema used by the 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.

In most cases, the files and modifications made by the REST endpoint generator are not complete. Developers must provide additional code. The places where additional coding is needed are flagged with the following comment:

TODO RestEndpointGenerator

You can search for these "TODO RestEndpointGenerator" comments in Studio to complete the configuration.

Common patterns used in the schema, mapping, and updater files

Generally speaking, fields in a data model entity follow one of the behaviors listed in the following table. For each behavior, there is a pattern for how that field is referenced in the schema definition files.


Field behavior	Example	Schema file	Mapping file	Updater file
Field is not exposed to Cloud API	Application internal information, such as `<entity>.CreateUser`	Omitted	Omitted	Omitted
Field is read-only	The `<entity>.id` field	Included; declared as `readOnly`	Included	Omitted
Field must be set during creation and cannot be changed thereafter	`Claim.LossDate`	Included; declared as `requiredForCreate`, `x-gw-nullable: false`, and `createOnly`	Included	Included
Field must be set during creation, but can be changed later	`Document.Status`	Included; declared as `requiredForCreate`, and `x-gw-nullable: false`	Included	Included
Field can be set or omitted during creation, and can later be changed	`Activity.Description`	Included	Included	Included

The swagger file

There is also a swagger file, which defines the endpoints themselves (the paths, operations, and associated resources). The REST endpoint generator adds code to this file. There is no requirement to modify this file, and there are no "TODO RestEndpointGenerator" comments in this file. However, a developer may wish to modify the file for the following reasons:

To change the API documentation text, such as the title and description of the endpoints
To remove an operation, such as DELETE