Resource Types

This document describes the core resource types in a ContentGrid application.

Overview

A ContentGrid application can be configured with kinds of entities that have attributes and relations.

A single instance of such an entity is generically referred to as an entity-item. Multiple entity-items of the same kind together form an entity-collection.

These two form the main resource types in a ContentGrid application. To support these resource types, a couple of additional resource types exist.

entity-item

An entity-item is a single, concrete instance of a certain entity.

Attributes are exposed as fields at the top level of the JSON object. Additionally, an id field is exposed, containing the unique id for the entity-item.

Some attribute types (like content) are exposed as a nested object, which contains the information stored in that attribute.

Like any HAL object, entity-item also has _links and _templates fields.

Example entity-item

This is an example of an invoice with a file in the document attribute.

{
  "id": "3211be1d-1ed1-4850-8ea6-3fa3218031f6",
  "received": "2024-07-15",
  "document": {
     "size": 123456,
     "mimetype": "application/pdf",
     "filename": "example-invoice.pdf"
  },
  "pay_before": "2024-08-14",
  "total_amount": 15.95,
  "_links": {
    [...]
  },
  "_templates": {
    [...]
  }
}

entity-collection

An entity-collection is an (ordered) set of entity-item resources.

Due to the usage of HAL, entity-items are available in a nested JSON object. The list of entity-items will always be located in _embedded.item.

All entity-items in a collection are always of the same type and expose the same attributes. The entity-items may be a reduced representation of a full entity-item resource, where some fields are omitted. The id field, which is used to address the individual entity will always be available.

Example entity-collection

This is an example of a collection of invoices

{
  "_embedded": {
    "item": [
      {
        "id": "3211be1d-1ed1-4850-8ea6-3fa3218031f6",
        "received": "2024-07-15",
        "document": {
            "size": 123456,
            "mimetype": "application/pdf",
            "filename": "example-invoice.pdf"
        },
        "pay_before": "2024-08-14",
        "total_amount": 15.95,
        "_links": {
            [...]
        },
        "_templates": {
          [...]
        }
      },
      {
        "id": "56fe1819-3f70-476c-937d-b400b660ee81",
        "received": "2020-01-01",
        "document": null,
        "pay_before": "2020-02-01",
        "total_amount": 123.4,
        "_links": {
            [...]
        },
        "_templates": {
          [...]
        }
      },
      [...]
    ]
  },
  "_links": {
    [...]
  },
  "page": {
    "size": 20,
    "next_cursor": "1wskufc1",
    "total_items_estimate": 38,
    "total_items_exact": 38
  }
}

Collection meta-information

The entity-collection contains meta-information about itself in the top-level page field:

Field	Type	Description
`size`	integer, >= 1	Page size; the maximum number of `entity-item` resources returned on a single page
`prev_cursor`	string or absent	Cursor to retrieve the previous page. Absent when there is no previous page
`next_cursor`	string or absent	Cursor to retrieve the next page. Absent when there is no next page
`total_items_estimate`	number, >= 0	Estimated total number of items in the collection. Also present when an exact count exists
`total_items_exact`	number, >= 0 or absent	Exact total number of items in the collection. Absent when calculation is too resource-intensive to execute

relation

The relation resource represents a relation between two entities. When reading, its format is dependent on whether it is a to-one or a to-many relation:

To-one relation (one-to-one, many-to-one): Reading returns a redirect to the linked entity-item
To-many relation (one-to-many, many-to-many): Reading returns a redirect to an entity-collection that contains all linked entity-items

relation-item

The relation-item resource represents a single item inside a to-many relation.

Reading returns a redirect to the entity-item, if it is linked in the relation.

entity-content

The entity-content resource represents the file contents that are stored on an entity attribute of type Content.

This resource contains arbitrary file contents, so no assumptions should be made about its format.

entities-root

The entities-root resource is the parent resource of all entity-collection resources.

It contains metadata about the application, in particular the list of all available entity types (in HAL format).

curl -i https://$APP_ID.$REGION.contentgrid.cloud/   \
    -H "Authorization: Bearer $TOKEN"

GET / HTTP/1.1
Authorization: Bearer $TOKEN

HTTP/1.1 OK
Content-Type: application/hal+json

{
  "_links": {
    "cg:entity": [
      {
        "href": "/invoices",
        "name": "invoice"
        [...]
      },
      {
        "href": "/suppliers",
        "name": "supplier"
        [...]
      }
    ],
    [...]
  }
}

entity-profile

The entity-profile resource is a computer-readable description of an entity type.

It describes the entity’s attributes, relations, constraints, and available operations. The full format is documented in the Entity Profiles reference.

profile-root

The profile-root resource is the parent resource of all entity-profile resources.

It contains metadata about the profiles, in particular the list of all available entity-profile types (in HAL format).