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 field. This field 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."
    }
  }
}