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.

For some types of data model fields, the modifications made by the REST endpoint generator are not complete. The places where additional coding may be 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