Skip to main content

Model Extension API

The Model Extension API provides a mechanism to retrieve and manage extensions on extendable elements within the model.

Extendable Element Data Object​

For elements that support extensions, their data object will include an additional extensions fieldFieldA property of a DataElement expanded to a database column and user interface input element.. This fieldFieldA property of a DataElement expanded to a database column and user interface input element. is an array containing references to the types of extensions attached to that element.

Example of an Extendable Element's Data Object:

{
  "data": {
    "id": "books::Book",
    "type": "elements::DataElement",
    "properties": [],
    "options": {},
    "extensions": [
      {
        "id": "elements::DataElement::QuerySearch",
        "label": "QuerySearch",
        "type": "expansionControl::ModelExtension",
        "format": "reference",
        "meta": {
          "count": "1", // Indicates the number of instances of this extension type
          "instance.type": "querysearch::QuerySearch" // The actual type of the extension instance
        },
        "links": {
          "instances": "{element_url}/extensions/QuerySearch", // Link to retrieve instances of this extension type
          "self": "/data/expansionControl%3A%3AModelExtension/elements%3A%3ADataElement%3A%3AQuerySearch" // Link to the extension type definition
        }
      }
    ]
  }
}

Each object within the extensions array provides metadata about an attached extension type, including a links.instances URL that can be used to retrieve the actual extension instances.

Endpoints​

These endpoints are used to interact with the extensions of a specific element. The {element_url} refers to the self-link of the extendable element (e.g. /model/{program_type}/{program_key}/{element_type}/{element_key} or /data/{element_type}/{element_key}).

1. Retrieve Extension Instances​

GET {element_url}/extensions/{extension_type}

Retrieves all instances of a specified extension_type that are attached to the target element.

Path Parameters:

  • {element_url}: The URL of the extendable element.
  • {extension_type}: The name of the extension type (e.g. QuerySearch).

Example:

To retrieve QuerySearch extensions for a Book element:

GET /data/books%3A%3ABook/myBookId/extensions/QuerySearch

2. Add a New Extension Instance​

POST {element_url}/extensions/{extension_type}

Adds a new instance of the specified extension_type to the target element. The request body should contain the data for the new extension instance.

Path Parameters:

  • {element_url}: The URL of the extendable element.
  • {extension_type}: The name of the extension type to add.

Request Body:

The structure of the request body will depend on the specific extension_type being added. It should contain the data representing the new extension instance.

Example:

To add a new QuerySearch extension to a Book element:

POST /data/books%3A%3ABook/myBookId/extensions/QuerySearch

{
  "data": {
    "type": "querysearch::QuerySearch",
    "properties": {
      "name": "BookSearch",
      "description": "QuerySearch element used for the JAX-RS REST API."
    }
  }
}