Entities and collections

In the OpenText Core Software Delivery Platform REST API, data is exchanged as JSON. A single entity is represented as a JSON object, and a collection of entities is represented as a JSON object that wraps an array of entities. This topic describes both representations.

Entity representation

An entity is a JSON object whose properties are its fields. The following fields identify an entity and, unless you request a specific set of fields, are returned by default. Of these, id and type are always returned, whether or not you request them:

Field Description

id

The unique identifier of the entity.

type

The type of the entity, such as defect.

subtype

The subtype of the entity, for types that have subtypes.

workspace_id

The workspace that the entity belongs to.

logical_name

A stable, human-readable identifier for the entity.

Beyond these fields, an entity has the fields defined by its metadata. Field values can be simple, such as strings and numbers, or they can be references to other entities.

Reference fields

A field can reference other entities:

  • A single-reference field is represented as an entity object, or as null when it has no value.

  • A multiple-reference field is represented as a collection object that contains a total_count and a data array of the referenced entities.

Collection representation

When you retrieve a collection, the response is a JSON object with the following properties:

  • total_count. The total number of entities that match the request.

  • data. An array of entity objects.

  • errors. An array of errors, used when an operation on multiple entities partially fails.

  • exceeds_total_count. Indicates whether the number of matching entities is larger than the reported total_count, which can happen when the count is capped.

{
    "total_count": 2,
    "exceeds_total_count": false,
    "data": [
        { "type": "defect", "id": "4001" },
        { "type": "defect", "id": "4002" }
    ],
    "errors": []
}

See also