Skip to main content

Model API Profiles

The model API uses profiles to ensure compatibility across diverse client setups. These profiles allow clients to customize how data from the model server is structured and formatted.

What is a Profile?​

A profile defines which properties of an element type (e.g., elements::DataElement) are relevant to a client and how they should be presented.

Each profile object has three key components:

  • name: A unique identifier for the profile.
  • elementType: The specific type of element the profile applies to (e.g., elements::DataElement).
  • properties: A list of property selection objects that specify which properties to include and how to handle referenced elements.

Property Selection Objects​

Within the properties list, each object defines how a particular property is handled:

  • property: (Required) The name of the property to include.
  • profile: (Optional) For properties that reference other elements, this specifies the name of a profile to apply to those referenced elements.
  • nestedProperties: (Optional) Alternatively, for referenced elements, you can provide a list of property selection objects to define which specific properties of the referenced elements should be included.

Important: A property selection object cannot have both profile and nestedProperties defined. If neither is specified for a reference property, the referenced elements will be formatted as simple reference objects.

Endpoints​

Create a Profile​

You can create a new profile using a POST request to the /profiles endpoint.

POST /profiles

Example Request Body:

{
    "name": "my-profile",
    "elementType": "elements::DataElement",
    "properties": [
        {
            "property": "name"
        },
        {
            "property": "fields",
            "profile": "default"
        },
        {
            "property": "finders",
            "nestedProperties": [
                {
                    "property": "name"
                }
            ]
        }
    ]
}

Retrieve a Profile​

To retrieve an existing profile, use a GET request to the following endpoint:

GET /profiles/{element_type}/{profile}

This request will return a 200 OK status if the profile exists, or a 404 Not Found if it doesn't.

How to Use a Profile​

To apply a profile to your API requests, simply pass the profile's name as a query parameter:

curl "${ELEMENT_URL}?profile=my-profile"