Configuring the schema file for generated endpoints

A schema file contains a definitions section that lists one or more schemas. Each schema is used to structure an API resource. For each schema, the following attributes are specified:

• A title and description, which is used for API definition documentation.
• The resource type, which is typically set to object.
• A list of properties. Each property includes:
  • A title and description, which is used for API definition documentation.
  • A type, which defines the JSON datatype of the property (for scalar values).
  • A ref, which defines the URI reference for the property (for compound values such as typekeys).
  • Optional attributes as needed for the business functionality of the property.

For example, the following is a portion of the schema for the base configuration Activity resource:

"Activity": {
  "title": "Activity",
  "description": "An `Activity` is an assignable item that represents a task to be done, a decision to be made, or information to be aware of",
  "type": "object",
  "properties": {
    "activityPattern": {
      "title": "Activity pattern",
      "description": "The code of the `ActivityPattern` used to create this activity and set its initial values",
      "type": "string"
      ...
      }
    },

The base configuration includes a set of API-specific extension schema files. The purpose of these files is to define schema information for custom resources for a given API. These files are named using the pattern <API>_ext-1.0.schema.json, where <API> is the internal name of the API. For example, the common_ext-1.0.schema.json file is used to define schema information for custom resources in the Common API. You can access extension schema files in Studio through the integration -> schemas -> ext -> <API>.v1 node.

When you generate endpoints for a custom entity, the REST endpoint generator adds the following code to the relevant extension schema file:

    "<resourceName>": {
      "title": "<custom entity name>",
      "description": "<custom entity name>",
      "type": "object",
      "properties": {
        // TODO RestEndpointGenerator : Add schema properties here
        "id": {
          "title": "ID",
          "description": "The unique identifier of this element",
          "type": "string",
          "readOnly": true
        }
      }
    }

For example, if you generate endpoints for a CustomEntity_Ext entity, the following is added to the extension schema file:

    "CustomEntityExt": {
      "title": "Custom entity ext",
      "description": "Custom entity ext",
      "type": "object",
      "properties": {
        // TODO RestEndpointGenerator : Add schema properties here
        "id": {
          "title": "ID",
          "description": "The unique identifier of this element",
          "type": "string",
          "readOnly": true
        }
      }
    }

Note that the REST endpoint generator provides properties information for only one property: id. The developer is responsible for:

• Deciding which fields from the custom entity must be available to the endpoints.
• Adding mapper information for those fields.

For example, suppose the CustomEntity_Ext entity included three fields:

• CustomDescription (a string)
• IsActive (a boolean)
• ExpirationDate (a datetime)

The developer decides CustomDescription and IsActive must be available to GETs, POSTs, or PATCHes. The developer would need to add the code shown below in bold.

    "CustomEntityExt": {
      "title": "Custom entity ext",
      "description": "Custom entity ext",
      "type": "object",
      "properties": {
        // TODO RestEndpointGenerator : Add schema properties here
        "id": {
          "title": "ID",
          "description": "The unique identifier of this element",
          "type": "string",
          "readOnly": true
        },
        "customDescription": {
          "title": "CustomDescription",
          "description": "The description for the CustomEntity",
          "type": "string"
        },
        "id": {
          "title": "isActive",
          "description": "Whether the CustomEntity is active",
          "type": "boolean"
        }
      }
    }

The developer also decides ExpirationDate must not be available to GETs and POST/PATCH responses. Therefore, this field is omitted from the schema.