Getting Started

This guide will walk you through the initial steps of setting up your organization, creating a project, and starting with data modeling in ContentGrid.

1. Create an Organization

Before you can create a data model, you need to have an organization.

1. On the main page, click the Create Organization button.
2. Follow the prompts to set up your organization.

If you already have an organization, you can skip this step.

2. Create a Project

Once your organization is set up:

1. Navigate to your organization page.
2. Click the Create Project button.

3. In the dialog, enter a name for your project and confirm.

3. Start Data Modeling

Now you can begin modeling your data:

1. Click the Add Entity button to start creating your first entity.

2. In the Data model tool, you can model your business entities. Click Add Entity, provide a name, and optionally a description. Providing a useful description is a good practice and can help some of the AI features in ContentGrid work better.

3. After creating your first entity, you can edit its name or delete it if needed.

Entities, Attributes, and Relations

Entities can have attributes and relationships to other entities.

Add an Attribute

1. Within an entity, click Add Attribute.
2. A dialog will appear with the following options:

• Property Name: A unique name within the entity.
• Type: The data type for this attribute. Options include:
  • Text
  • Integer
  • Decimal
  • Boolean
  • Date
  • Content (binary object or file)
  • Audit Metadata (automatically managed subfields: createdBy, createdAt, modifiedBy, modifiedAt)

3. After creating the attribute, you can edit it further:

• Name: Rename the attribute.
• Description: Add a description to help users and AI agents.
• Search Options:
  • Search values exactly: Values must match exactly when searching (useful for status, category, etc.).
  • Search values starting with given prefix: Values can be searched by prefix (case- and accent-insensitive; useful for names, titles, etc.).
• Constraints:
  • Value is required: Attribute must have a value for the item to be created.
  • Must be unique: Attribute value must be unique across all items.
  • Set allowed values: Provide a list of allowed values; only these can be used.

Add a Relation

You can model relationships to other entities (or to the same entity):

1. Click Add Relation.
2. In the pop-up dialog, configure the following:

• From: The current entity.
• To: The target entity for the relationship.
• Name: Name of the relationship.
• Description: (Optional) Description for the relationship.
• Cardinality: Cardinality of the relationship (e.g., one-to-one, one-to-many). Choose the checkboxes that apply.
• Relationship is required: Check if this relationship must always exist.

Permission Policies

Permission Policies

ContentGrid takes a different approach to permissions than legacy content management systems. Instead of making a complex hierarchical tree structure of permissions with inheritance, a set of permission policies describes access for each entity. These policies are rules that contain logical expressions, making use of (a combination of) entity attributes and user attributes.

How to create a Policy

First, go to the Permissions modeler:

To create our first policy, we first have to choose the entity for which we are going to create a policy:

When clicking the “Create Policy” button you will see the configuration options for creating a new policy:

First, you’ll have to choose for which operation this policy will be evaluated. The options are: Read, Create, Update, Delete. You can choose one or more operations.

By choosing the visibility setting, you can define if this policy is applicable for authenticated users only, or for all users.

The “Additional conditions” section is where you define the conditions for this policy, access to the entity is granted when the conditions are fulfilled.

Multiple conditions can be applied, and each rule has a left and a right side, that are compared to each other. Both left and right sides of can be a “user attribute”, “entity attribute” or constant. The possible comparisons between the left and the right side are:

• equals
• not equals
• greater than
• greater or equals
• less than
• less than or equals
• contains
• in

You can add more conditions with the “Add Condition” button. All conditions have to be satisfied before a policy grants access. Save the policy with the “Add Policy” button.

Now, you should see your policy for this entity in the overview.

Webhooks

Tutorial on webhooks

Webhooks are one way that ContentGrid applications can send automated messages or information to external systems. They are almost always faster than polling, and require less work on your end.

Each mutating operation on an resource is handled individually and is asynchronously, but almost immediately delivered to the configured webhook endpoint.

A ContentGrid Webhook

• is always attached to a ContentGrid entity and selected change triggers
• is delivered to a configured HTTP endpoint
• is delivered as a HTTP POST message with a body payload and specific ContentGrid HTTP headers

Create New Webhook?

First, go to the Webhooks modeler:

To create our first Webhook, we first have to click on Create Webhook:

When clicking the “Create Webhook” button you will see the configuration options for creating a new Webhook:

• First, you will have to give a satisfying Webhook name (or description).
• Then you have to choose for which entity this Webhook will be applied
• After the entity selection, select the notifications triggers, where the options are
  • create (whenever the selected entity type is created)
  • update (when each existing entity is being updated)
  • content (when a document content has been changed)
  • delete (when the enetity selected has been deleted)
• As a last step, you have to provide the Webhook URL to be invoked by your ContentGrid application

After clicking save, the Webhook is saved and is listed in the overview but will only be available to your ContentGrid runtime application once you create a new release.

You can add more Webhooks with the “Create Webhook” button.

Webhook endpoint

A Webhook endpoint has some specific constraints and must respect the following implementation details:

• it has to support the HTTP POST method
• should accept a JSON body and application/json Content-Type
• can use our ContentGrid HTTP headers in order to validate that the delivered message is coming from our platform
  • User-Agent value is ContentGrid-Slingshot/APP_VERSION
  • ContentGrid-Application-Id contains the application id
  • ContentGrid-Deployment-Id contains the deployment id
  • ContentGrid-Signature provides a JWT signed by the our platform that should be used in order that the message is actually sent by the ContentGrid platform

Security and validation

ContentGrid signs JWTs using asymmetric encryption (RS256), and publishes the public signing keys in a JWKS (JSON Web Key Set).

The signing keys are rotated on a regular basis.

• We discourage doing manual JWT validation since it might be easy to improperly implement and miss some important details that will lead to serious security vulnerabilities. Most JWT libraries take care of JWT validation for you.
• We also highly recommend to use a JWK library for the programming language of your choice.

One of the benefits of JSON Web Token (JWT) is that you can validate a token using an easy cryptographic operation.

What are JWKs?

A JSON Web Key (JWK) is a JSON data structure that represents a cryptographic key. JWKs are a set of keys shared between different services and are used to verify the JWT token from the authorization server.

You should only be validating the received JWT against ContentGrid Json Web Key (JWK) URL which is ${CONTENTGRID_URL}/.well-known/jwks.json

We use JWKS to expose the public keys used by the ContentGrid platform to all the clients required to validate signatures.

For more information you can check the JWK RFC

The example of a JWKS is something that looks like this:

{
  "keys": [
    {
      "use": "sig",
      "kty": "RSA",
      "kid": "UVelusmvyM2xScEu0F_xSNlhelC5jZTD77R_3mmOZXs",
      "alg": "RS256",
      "n": "...yjXzcFpbMJB1fIFam9lQBeXWbTqzJwbuFbspHMsRowa8FaPw44l2C9Q42J3AdQD8CcN...",
      "e": "AQAB"
    },
    {
        ...
    }
  ]
}

In the above example some important fields are

• e: is the exponent for a standard pem
• n: is the moduluos for a standard pem
• alg: the signing algorithm.
• kid: a unique id for every key in the set.

ContentGrid’s JWT headers and claims:

{
  "kid": "UVelusmvyM2xScEu0F_xSNlhelC5jZTD77R_3mmOZXs",
  "alg": "RS256"
}.{
  "aud": "https://webhooks-demo.rtp-scw-sandbox.contentgrid.cloud/broker-process",
  "exp": 1679044765,
  "iat": 1679044465,
  "jti": "df475d5a-fc0e-4fca-a03a-c279e86fe9ed"
}.[Signature]

• kid: is Identifier of the static key used to sign the JWT
• alg: Algorithm used to sign the key
• aud: Recipients that the JWT is intended for (the CG Application URL)
• iat: The issuing time of the token in seconds
• exp: The expiration time of the token in seconds
• jti: Unique identifier of the token

Get the signing keys

Here is a Java exmaple of how to validate a JWT using JWKs with Nimbus JOSE + JWT

• To validate the token, first, you need to get the JSON web key set from the JWKs endpoint. The token will be received as JSON in the validation endpoint in the body.

ResourceRetriever jwkSetRetriever = new DefaultResourceRetriever();
JWKSource<SecurityContext> jwkSource = new RemoteJWKSet<>(URI.create("${CONTENTGRID_URL}/.well-known/jwks.json").toURL(), jwkSetRetriever);
JWSKeySelector<SecurityContext> jwsKeySelector = JWSAlgorithmFamilyJWSKeySelector.fromJWKSource(jwkSource);

• Additional validation for token claims

ConfigurableJWTProcessor<SecurityContext> jwtProcessor = new DefaultJWTProcessor<>();
jwtProcessor.setJWSKeySelector(jwsKeySelector);

jwtProcessor.setJWTClaimsSetVerifier((claims, context) -> {
	final Date now = new Date();			
	final Date exp = claims.getExpirationTime();
	if (exp != null) {
		if (now.after(exp)) {
			throw new BadJWTException("expired");
		}
	}
});	

• and the JWT validation

SignedJWT signedJWT = SignedJWT.parse(THE_JWT);	
jwtProcessor.process(signedJWT, null);

This short guide provides the basic steps required to locally verify an access or ID token signed by ContentGrid. It uses packages from Nimbus JOSE + JWT for key parsing and token validation, but the general principles should apply to any JWT validation library.

Navigator overview

(1) Entity menu

The entity menu allows you to select an entity type for search and creation. The selected entity is highlighted.

(2) Search form

In the search form you can search on the searchable metadata of the entity and it’s related entities, as defined in the Console.

(3) Results table

The results table shows up after search and displays the search results as a table with metadata. Clicking one of the lines in the table will open the document preview.

(4) Create entity button

Clicking the create entity button will bring you to create form where you can fill in the metadata, files and link the relations for this entity.

(5) Document preview

The document preview will display a preview of the line selected in the results table. If there are multiple files attached to that entity, there will be a dropdown selector to choose what file you want to preview.

Creating entities

(1) Create form

In the create form you can fill in the metadata fields of the entity you are creating. Mandatory fields are indicated with an asterisk. Datetime fields have a datetime picker. Content fields support drag and drop and opening a file picker.

(2) Relation field

If your entity has a relation to another relation, you will see that in the form. The link data button will bring you to the link relation popover where you can link the correct entities.

(3) Extract button

The extract button will open a pop-up to start an automated metadata extraction using AI based on the files you already uploaded in the form.

(4) Create/cancel buttons

These buttons allow you to submit or cancel the entity creation.

(5) Document preview

The document preview allows you to see the documents added next to the form. This can be practical when you need to read data from the document to fill in the form. The extract feature will also overlay information in the preview when used.

Link relation

After clicking the link data button in the create form a popover will appear that will help you link related entities.

(1) Search form

The search form in this popover functions similarly to the entity search form and searches on the linked entity.

(2) Result table

After pressing the “SEARCH” or “SHOW ALL” button, the results table shows the candidates for linking. Just click a line to link the entity. It is possible to link multiple entities if it is a “TO MANY” relationship.

(3) Create button

This button will open a new tab on the create form of the entity type you are trying to link. Use this when the entity you want to link does not yet exist.

Authentication

An access token is required to access a ContentGrid Application.

Access tokens are always obtained through OpenID Connect (OIDC). The authentication token contains user identity information and the IAM attributes assigned to the user.

OIDC clients

To identify the application that performs the authentication, an OIDC client needs to be registered in the Organization’s IAM Realm. An Organization can have multiple IAM Realms; ensure you are using the same Realm as the one used by the Application.

An OIDC client can be configured in the “Clients” tab of the IAM Realm.

Setting up an OIDC connection requires 3 configuration parameters that can be obtained from the OIDC client page:

1. Issuer URI
2. Client ID
3. Client Secret

OIDC configuration can be discovered from the Issuer URI using OIDC Discovery. If OIDC discovery is not supported by your software, you can obtain the authorization and token endpoints manually from the discovery document, but this is not recommended.

Service account authentication

When using service account authentication, the access token is issued with its own privileges instead of with the privileges of a user.

To authenticate as a service account, you need to use the Client credentials grant.

By default, no IAM attributes are assigned to a service account. These need to be set up if the applicable permission policies require it to provide access.

curl https://auth.$REGION.contentgrid.cloud/realms/$REALM/protocol/openid-connect/token    \
  -u $CLIENT_ID:$CLIENT_SECRET       \
  -d grant_type=client_credentials

User authentication

When using user authentication, the access token is issued with the privileges of the user.

To use user authentication, you need to use the Authorization code grant. This flow will necessary include a pass through the user’s web browser as part of the flow to obtain an access token.

Supplying credentials to the application

The access token is supplied to the application by using bearer authorization.

Other methods of supplying access tokens (like an access_token query parameter or form-encoded body parameter) are not supported.

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

GET / HTTP/1.1
Authorization: Bearer $TOKEN

API Usage

ContentGrid applications expose a REST API using JSON as a response format. All JSON responses use HAL as a hypertext format, linking to related resources. Actions that can be taken on resources are specified using the HAL-FORMS format.

Before using the API, you need to authenticate and obtain an access token.

This documentation covers the basics of using the Application REST API, advanced usage with HAL is described in HAL Usage.

Because the specific API is generated from the configured data model, the examples will use an example datamodel.

OpenAPI spec

An OpenAPI spec for your application’s datamodel is available from the ContentGrid Console. Every Release has its own associated OpenAPI spec, which you can view or download.

For deployed applications, a copy of the OpenAPI spec is also available on /openapi.yaml (after authentication).

Resource types

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. Their relation to the main resource types is explained in the Resource Types reference.

Basic operations

This section explains all the basic operations (create, read, update, delete) for the resource types.

The operations are explained in their minimal form, without any request modifiers applied.

REGION="<Region where the application is deployed>"
APP_ID="<ID of the application>"
REALM="<Internal reference of your IAM Realm>"
CLIENT_ID="<IAM Service account Client ID>"
CLIENT_SECRET="<IAM Service account Client Secret>"

TOKEN="$(curl -Ss https://auth.$REGION.contentgrid.cloud/realms/$REALM/protocol/openid-connect/token    \
 -u $CLIENT_ID:$CLIENT_SECRET       \
 -d grant_type=client_credentials | jq .access_token -r)"

INVOICE_ID="$(curl -Ss https://$APP_ID.$REGION.contentgrid.cloud/invoices   \
    -F "total_amount=15.95"   \
    -F "received=2024-07-15"   \
    -F "pay_before=2024-08-14"   \
    -F "document=dummy-invoice;filename=invoice.txt;type=text/plain"   \
    -H "Authorization: Bearer $TOKEN"   \
    | jq .id -r
)"
INVOICE2_ID="$(curl -Ss https://$APP_ID.$REGION.contentgrid.cloud/invoices   \
    -F "total_amount=123.4"   \
    -F "received=2020-01-01"   \
    -F "pay_before=2020-02-01"   \
    -H "Authorization: Bearer $TOKEN"   \
    | jq .id -r
)"
SUPPLIER_ID="$(curl -Ss https://$APP_ID.$REGION.contentgrid.cloud/suppliers   \
    -F "name=Test supplier"   \
    -F "telephone=test"   \
    -H "Authorization: Bearer $TOKEN"   \
    | jq .id -r
)"

entity-item operations

An entity-item resource is exposed on the path /<entity-name-plural>/{id} (e.g. /invoices/{id} for the invoice entity type). {id} is a placeholder for the actual ID of the entity-item.

The following operations are available:

{
  "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": {
    [...]
  }
}

curl -i -X PUT https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE_ID   \
    --json "{\"pay_before\": \"2024-08-31\", \"received\": \"2024-07-15\", \"total_amount\": 15.95}"   \
    -H "Authorization: Bearer $TOKEN"

PUT /invoices/$INVOICE_ID HTTP/1.1
Authorization: Bearer $TOKEN
Content-Type: application/json

{"pay_before": "2024-08-31", "received": "2024-07-15", "total_amount": 15.95}

HTTP/1.1 204 No Content

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

GET /invoices/$INVOICE_ID HTTP/1.1
Authorization: Bearer $TOKEN

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "3211be1d-1ed1-4850-8ea6-3fa3218031f6",
  "received": "2024-07-15",
  "document": null,
  "pay_before": "2024-08-31",
  "total_amount": 15.95,
  "_links": {
    [...]
  },
  "_templates": {
    [...]
  }
}

curl -i -X PATCH https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE_ID   \
    --json "{\"pay_before\": \"2024-08-31\", \"received\": \"2024-07-15\", \"total_amount\": 15.95}"   \
    -H "Authorization: Bearer $TOKEN"

PATCH /invoices/$INVOICE_ID HTTP/1.1
Authorization: Bearer $TOKEN
Content-Type: application/json

{"pay_before": "2024-08-31", "received": "2024-07-15", "total_amount": 15.95}

HTTP/1.1 204 No Content

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

GET /invoices/$INVOICE_ID HTTP/1.1
Authorization: Bearer $TOKEN

HTTP/1.1 200 OK
Content-Type: application/json

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

entity-collection operations

The entity-collection resource is exposed on the path /<entity-name-plural> (e.g. /invoices for the invoice entity type).

The following operations are available:

curl -i https://$APP_ID.$REGION.contentgrid.cloud/invoices   \
    --json "{\"received\": \"2024-07-15\", \"total_amount\": 15.95, \"pay_before\": \"2024-08-14\"}"   \
    -H "Authorization: Bearer $TOKEN"

POST /invoices HTTP/1.1
Authorization: Bearer $TOKEN
Content-Type: application/json

{"received": "2024-07-15", "total_amount": 15.95, "pay_before": "2024-08-14"}

HTTP/1.1 201 Created
Location: /invoices/3211be1d-1ed1-4850-8ea6-3fa3218031f6
Content-Type: application/prs.hal-forms+json

{
  "id": "3211be1d-1ed1-4850-8ea6-3fa3218031f6",
  "received": "2024-07-15",
  "document": null,
  "pay_before": "2024-08-14",
  "total_amount": 15.95,
  "_links": {
    [...]
  },
  "_templates": {
    [...]
  }
}

curl -i https://$APP_ID.$REGION.contentgrid.cloud/invoices   \
    -F received=2024-07-15   \
    -F total_amount=15.95   \
    -F pay_before=2024-08-14   \
    -F document=@example-invoice.pdf   \
    -H "Authorization: Bearer $TOKEN"

POST /invoices HTTP/1.1
Authorization: Bearer $TOKEN
Content-Type: multipart/form-data;boundary="delimiter123"

--delimiter123
Content-Disposition: form-data; name="received"

2024-07-15
--delimiter123
Content-Disposition: form-data; name="total_amount"

15.95
--delimiter123
Content-Disposition: form-data; name="pay_before"

2024-08-14
--delimiter123
Content-Disposition: form-data; name="document"; filename="example-invoice.pdf"

....Omitted contents of file example-invoice.pdf....
--delimiter123--

HTTP/1.1 201 Created
Location: /invoices/3211be1d-1ed1-4850-8ea6-3fa3218031f6
Content-Type: application/prs.hal-forms+json

{
  "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": {
    [...]
  }
}

Collection query parameters

An entity-collection has 3 query parameters that control the collection itself:

Pagination

By default, every page contains 20 entity-items. This can be changed with the _size query parameter.

When there are multiple pages, the meta information will contain prev_cursor and/or next_cursor fields. A previous or next page can be retrieved by setting the _cursor query parameter to the value in the prev_cursor or next_cursor field.

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

GET /invoices HTTP/1.1
Authorization: Bearer $TOKEN

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json

{
    "_embedded": {
        [...]
    },
    "page": {
        "size": 20,
        "next_cursor": "1wskufc1",
        "total_items_estimate": 48,
        "total_items_exact": 48
    }
}

curl -i https://$APP_ID.$REGION.contentgrid.cloud/invoices?_cursor=1wskufc1   \
    -H "Authorization: Bearer $TOKEN"

GET /invoices?_cursor=1wskufc1 HTTP/1.1
Authorization: Bearer $TOKEN

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json

{
    "_embedded": {
        [...]
    },
    "page": {
        "size": 20,
        "prev_cursor": "0dtcbvz0",
        "next_cursor": "0qk2h5e2",
        "total_items_estimate": 48,
        "total_items_exact": 48
    }
}

curl -i https://$APP_ID.$REGION.contentgrid.cloud/invoices?_cursor=0qk2h5e2   \
    -H "Authorization: Bearer $TOKEN"

GET /invoices?_cursor=0qk2h5e2 HTTP/1.1
Authorization: Bearer $TOKEN

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json

{
    "_embedded": {
        [...]
    },
    "page": {
        "size": 20,
        "prev_cursor": "1wskufc1",
        "total_items_estimate": 48,
        "total_items_exact": 48
    }
}

Sorting

By default, the collection is not sorted. The collection can be sorted by using the _sort query parameter.

The _sort query parameter can be repeated multiple times to sort on multiple attributes.

The _sort value is composed of the attribute name, followed by ,asc or ,desc to sort ascending or descending.

Note that not all attributes support sorting. The OpenAPI spec lists the valid values for the _sort query parameter.

curl -i https://$APP_ID.$REGION.contentgrid.cloud/invoices?_sort=received,asc\&_sort=total_amount,desc   \
    -H "Authorization: Bearer $TOKEN"

GET /invoices?_sort=received,asc&_sort=total_amount,desc HTTP/1.1
Authorization: Bearer $TOKEN

Filtering

Search filters can be applied to the entity-collection. By default no filters are applied.

All filters are application-specific, and are mapped directly to query parameters. The OpenAPI spec lists all the valid filters as query parameters.

Multiple search filters can be combined. Different search filters are AND’ed together; repeating the same search filter multiple times will perform an OR on the different values of that filter.

curl -i https://$APP_ID.$REGION.contentgrid.cloud/invoices?total_amount=15.95   \
    -H "Authorization: Bearer $TOKEN"

GET /invoices?total_amount=15.95 HTTP/1.1
Authorization: Bearer $TOKEN

curl -i https://$APP_ID.$REGION.contentgrid.cloud/invoices?total_amount=19.95\&total_amount=123.4   \
    -H "Authorization: Bearer $TOKEN"

GET /invoices?total_amount=19.95&total_amount=123.4 HTTP/1.1
Authorization: Bearer $TOKEN

curl -i https://$APP_ID.$REGION.contentgrid.cloud/invoices?total_amount=15.95\&pay_before=2024-08-14   \
    -H "Authorization: Bearer $TOKEN"

GET /invoices?total_amount=15.95&pay_before=2024-08-14 HTTP/1.1
Authorization: Bearer $TOKEN

curl -i https://$APP_ID.$REGION.contentgrid.cloud/invoices?total_amount=15.95\&total_amount=123.4\&pay_before=2024-08-14   \
    -H "Authorization: Bearer $TOKEN"

GET /invoices?total_amount=15.95&total_amount=123.4&pay_before=2024-08-14 HTTP/1.1
Authorization: Bearer $TOKEN

relation operations

An entity can have relations to a different entity. These are exposed on the path /<entity-name-plural>/{id}/<relation-name>. (e.g. /invoices/{id}/supplier for the invoice entity type and a relation supplier)

Depending on the relation type, the available operations and responses are different.

to-one relation operations

These operations are applicable to one-to-one and many-to-one relations.

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

GET /invoices/$INVOICE_ID/supplier HTTP/1.1
Authorization: Bearer $TOKEN

HTTP/1.1 404 Not Found

curl -i -X PUT https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE_ID/supplier   \
    --data-binary "https://$APP_ID.$REGION.contentgrid.cloud/suppliers/$SUPPLIER_ID"   \
    -H 'Content-Type: text/uri-list'   \
    -H "Authorization: Bearer $TOKEN"

PUT /invoices/$INVOICE_ID/supplier HTTP/1.1
Authorization: Bearer $TOKEN
Content-Type: text/uri-list

https://$APP_ID.$REGION.contentgrid.cloud/suppliers/$SUPPLIER_ID

HTTP/1.1 204 No Content

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

GET /invoices/$INVOICE_ID/supplier HTTP/1.1
Authorization: Bearer $TOKEN

HTTP/1.1 302 Found
Location: /suppliers/$SUPPLIER_ID

to-many relation operations

These operations are applicable to one-to-many and many-to-many relations.

curl -i -X POST https://$APP_ID.$REGION.contentgrid.cloud/suppliers/$SUPPLIER_ID/invoices   \
    --data-binary "https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE_ID
https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE2_ID"   \
    -H 'Content-Type: text/uri-list'   \
    -H "Authorization: Bearer $TOKEN"

POST /suppliers/$SUPPLIER_ID/invoices HTTP/1.1
Authorization: Bearer $TOKEN
Content-Type: text/uri-list

https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE_ID
https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE2_ID

HTTP/1.1 204 No Content

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

GET /suppliers/$SUPPLIER_ID/invoices HTTP/1.1
Authorization: Bearer $TOKEN

HTTP/1.1 302 Found
Location: /invoices?_internal_supplier=$SUPPLIER_ID

relation-item operations

A to-many relation also has a way to reference an individual item inside the relation; the relation-item resource. These are exposed on the path /<entity-name-plural>/{id}/<relation-name>/{itemId} (e.g. /suppliers/{id}/invoices/{itemId} for the supplier entity type and a relation invoices).

curl -i -X DELETE https://$APP_ID.$REGION.contentgrid.cloud/suppliers/$SUPPLIER_ID/invoices/$INVOICE_ID   \
    -H "Authorization: Bearer $TOKEN"

DELETE /suppliers/$SUPPLIER_ID/invoices/$INVOICE_ID HTTP/1.1
Authorization: Bearer $TOKEN

HTTP/1.1 204 No Content

curl -i -X DELETE https://$APP_ID.$REGION.contentgrid.cloud/suppliers/$SUPPLIER_ID/invoices/$INVOICE_ID   \
    -H "Authorization: Bearer $TOKEN"

DELETE /suppliers/$SUPPLIER_ID/invoices/$INVOICE_ID HTTP/1.1
Authorization: Bearer $TOKEN

HTTP/1.1 404 Not Found

entity-content operations

An entity-content resource is exposed on the path /<entity-name-plural>/{id}/<attribute-name> (e.g. /invoices/{id}/document for the invoice entity type and a content attribute document). {id} is a placeholder for the actual ID of the entity-item.

The following operations are available:

For the GET and PUT with arbitrary Content-Type; the filename is provided in the Content-Disposition header. If no filename is provided during content upload, the filename field of the content attribute will be set to null

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

GET /invoices/$INVOICE_ID/document HTTP/1.1
Authorization: Bearer $TOKEN

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment;filename="example-invoice.pdf"

....Raw PDF body omitted....

curl -i -X PUT https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE_ID/document   \
    --data-binary "@example-invoice.pdf"   \
    -H 'Content-Disposition: attachment;filename="example-invoice.pdf"'   \
    -H 'Content-Type: application/pdf'   \
    -H "Authorization: Bearer $TOKEN"

PUT /invoices/$INVOICE_ID/document HTTP/1.1
Authorization: Bearer $TOKEN
Content-Disposition: attachment;filename="example-invoice.pdf"
Content-Type: application/pdf

....Omitted contents of file example-invoice.pdf....

HTTP/1.1 204 No Content

curl -i -X PUT https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE_ID/document   \
    -F file=@example-invoice.pdf   \
    -H "Authorization: Bearer $TOKEN"

PUT /invoices/$INVOICE_ID/document HTTP/1.1
Authorization: Bearer $TOKEN
Content-Type: multipart/form-data;boundary="delimiter123"

--delimiter123
Content-Disposition: form-data; name="file"; filename="example-invoice.pdf"

....Omitted contents of file example-invoice.pdf....
--delimiter123--

HTTP/1.1 204 No Content

Request modifiers

The basic operations explained above can be extended with additional functionality. Additional functionality is layered on top of the basic operations using HTTP headers.

Conditional requests

Conditional requests allow to check a precondition before applying the request to the target resource. They are an implementation of RFC9110 Conditional Requests.

The primary usage of conditional requests is to prevent the “lost update” problem, where one system overwrites the changes of another system that made a write between the read and write of the first system.

sequenceDiagram
    autonumber
    participant a as System A
    participant s as ContentGrid API
    participant b as System B

    a ->>+ s: GET item
    s -->>- a: 200 OK<br>ETag: "abc"<br>original data

    b ->>+ s: PUT item<br>new data
    s -->>- b: 204 No Content<br>ETag: "def"

    a ->>+ s: PUT item<br>other data
    s -->>- a: 204 No Content<br>ETag: "mno"
    note over a, s: "new data" was accidentally<br>overwritten by "other data"<br>without System A having seen it

sequenceDiagram
    autonumber
    participant a as System A
    participant s as ContentGrid API
    participant b as System B

    a ->>+ s: GET item
    s -->>- a: 200 OK<br>ETag: "abc"<br>original data

    b ->>+ s: PUT item<br>new data
    s -->>- b: 204 No Content<br>ETag: "def"

    a ->>+ s: PUT item<br>If-Match: "abc"<br>other data
    rect red
    s -->>- a: 419 Precondition Failed
    note over a, s : request was rejected<br>System A did not accidentally<br>overwrite the "new data"
    end

Conditional requests can be used on the resources that have an ETag response header, which are these:

To perform conditional requests, a previously obtained ETag value has to be placed in the If-Match or If-None-Match headers. Note that the quotes are part of the ETag value.

The If-Modified-Since and If-Unmodified-Since headers are not supported, because no Last-Modified response header is present, and they are less precise.

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

GET /invoices/$INVOICE_ID HTTP/1.1
Authorization: Bearer $TOKEN

HTTP/1.1 200 OK
ETag: "1e0k4j9"
Content-Type: application/hal+json

{
  "id": "019be613-baa4-7644-9438-e252be3bbe84",
  "received": "2024-07-15",
  "document": {
    "filename": "invoice.txt",
    "length": 13,
    "mimetype": "text/plain"
  },
  "pay_before": "2024-08-14",
  "total_amount": 15.95,
  "_links": {
    [...]
  }
}

curl -i -X PATCH https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE_ID   \
    --json "{\"pay_before\": \"2024-08-13\"}"   \
    -H 'If-Match: "1e0k4j9"'   \
    -H "Authorization: Bearer $TOKEN"

PATCH /invoices/$INVOICE_ID HTTP/1.1
Authorization: Bearer $TOKEN
If-Match: "1e0k4j9"
Content-Type: application/json

{"pay_before": "2024-08-13"}

HTTP/1.1 204 No Content
ETag: "i4xcj6"

curl -i -X PATCH https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE_ID   \
    --json "{\"pay_before\": \"2024-08-13\"}"   \
    -H 'If-Match: "1e0k4j9"'   \
    -H "Authorization: Bearer $TOKEN"

PATCH /invoices/$INVOICE_ID HTTP/1.1
Authorization: Bearer $TOKEN
If-Match: "1e0k4j9"
Content-Type: application/json

{"pay_before": "2024-08-13"}

HTTP/1.1 412 Precondition Failed
Content-Type: application/problem+json

{
  "type": "https://contentgrid.cloud/problems/unsatisfied-version",
  "title": "Object has changed",
  "detail": "Requested version constraint 'is any of [exactly '1e0k4j9']' can not be satisfied (actual version exactly '1r061qt')",
  "status": 412,
  "actual_version": "1r061qt"
}

Range requests

Range requests allow retrieving a partial representation of the entity-content resource. They are an implementation of RFC9110 Range Requests.

Range requests are only supported on the entity-content resource (/<entity-name-plural>/{id}/<attribute-name>), as indicated by the Accept-Ranges header.

You usually don’t use range requests directly, but some tools that work with potentially large files (like PDF viewers or download managers) can make use of them.

curl -i https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE_ID/document   \
    -H 'Range: bytes=0-3'   \
    -H "Authorization: Bearer $TOKEN"

GET /invoices/$INVOICE_ID/document HTTP/1.1
Authorization: Bearer $TOKEN
Range: bytes=0-3

HTTP/1.1 206 Partial Content
Accept-Ranges: bytes
Content-Range: bytes 0-3/13
ETag: "8xhtyfikrvnts4izydc95vfcn"
Content-Length: 4
Content-Type: text/plain

dumm

curl -i https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE_ID/document   \
    -H 'If-Match: "8xhtyfikrvnts4izydc95vfcn"'   \
    -H 'Range: bytes=4-'   \
    -H "Authorization: Bearer $TOKEN"

GET /invoices/$INVOICE_ID/document HTTP/1.1
Authorization: Bearer $TOKEN
If-Match: "8xhtyfikrvnts4izydc95vfcn"
Range: bytes=4-

HTTP/1.1 206 Partial Content
Accept-Ranges: bytes
Content-Range: bytes 4-12/13
ETag: "8xhtyfikrvnts4izydc95vfcn"
Content-Length: 9
Content-Type: text/plain

y-invoice

HAL Usage

ContentGrid applications expose a REST API using JSON as a response format. All JSON responses use HAL as a hypertext format, linking to related resources. Actions that can be taken on resources are specified using the HAL-FORMS format.

Before using the API, you need to authenticate and obtain an access token.

This guide explains how HAL features make the API discoverable and how to leverage HAL features to build robust integrations.

Basic usage of the API, where no automatic adaptations to the data model are necessary is described in API Usage.

When to use HAL?

Using HAL is only recommended when building integrations with ContentGrid that have to dynamically discover the datamodel and adjust to it.

It is particularly useful for systems that integrate with multiple distinct ContentGrid applications, which will have different datamodels.

When building such a dynamic system, you want it to automatically discover the datamodel and automatically adjust to it when it changes.

HAL provides several benefits for these systems:

• Discoverability: Navigate the API by following links instead of constructing URLs manually
• Flexibility: Discover available operations dynamically instead of hardcoding them
• Evolvability: Adapt to data model changes without breaking your integration
• Self-documentation: The API tells you what actions are possible on each resource

HAL Basics

HAL and HAL-FORMS are built on top of JSON. They add 3 special fields to the resource objects:

• _links: Contains links to related resources
• _embedded: Directy embeds related resources
• _templates: Describes operations that can be performed on this resource (HAL-FORMS)

{
  "id": "3211be1d-1ed1-4850-8ea6-3fa3218031f6",
  "received": "2024-07-15",
  "document": null,
  "pay_before": "2024-08-14",
  "total_amount": 15.95,
  "_links": {
    "self": {
      "href": "https://app.contentgrid.example/invoices/3211be1d-1ed1-4850-8ea6-3fa3218031f6"
    },
    "cg:relation": [
      {
        "href": "https://app.contentgrid.example/invoices/3211be1d-1ed1-4850-8ea6-3fa3218031f6/supplier",
        "title": "Supplier",
        "name": "supplier"
      }
    ],
    "cg:content": [
      {
        "href": "https://app.contentgrid.example/invoices/3211be1d-1ed1-4850-8ea6-3fa3218031f6/document",
        "title": "Document",
        "name": "document"
      }
    ],
    "curies": [
      {
        "href": "https://contentgrid.cloud/rels/contentgrid/{rel}",
        "name": "cg",
        "templated": true
      }
    ]
  },
  "_templates": {
    "default": {
      "method": "PUT",
      "contentType": "application/json",
      "properties": [
        {
          "name": "received",
          "prompt": "Received",
          "required": true,
          "type": "datetime"
        },
        {
          "name": "pay_before",
          "prompt": "Pay before",
          "required": true,
          "type": "datetime"
        },
        {
          "name": "total_amount",
          "prompt": "Total amount",
          "required": true,
          "type": "number"
        }
      ]
    },
    "delete": {
      "method": "DELETE",
      "properties": []
    },
    "set-supplier": {
      "method": "PUT",
      "contentType": "text/uri-list",
      "properties": [
        {
          "name": "supplier",
          "type": "url"
        }
      ],
      "target": "https://app.contentgrid.example/invoices/3211be1d-1ed1-4850-8ea6-3fa3218031f6/supplier"
    },
    "clear-supplier": {
      "method": "DELETE",
      "properties": [],
      "target": "https://app.contentgrid.example/invoices/3211be1d-1ed1-4850-8ea6-3fa3218031f6/supplier"
    }
  }
}

Working with Links

Links connect resources together. Instead of constructing URLs yourself, you use the provided link to go to the related resource.

Link Relation Types

Links express a relation between the resource they appear on (the link context), and the link target. The link relation type (RFC8288 Sec 3.3) determines the kind of relation between the link context and the link target.

Next to the standard link relation types, ContentGrid defines extension link relation types.

CURIEs

CURIEs (Compact URIs) are a shorthand notation for extension link relation types. They are used as defined in the HAL specification. Before comparing a link relation, a CURIE must be expanded into the full URI.

See the Link Relation Types reference for the formal definition of CURIE expansion and examples.

Working with Embedded Resources

Instead of linking to a related resource, it is also possible to directly embed it in the main resource. This is of only possible when the resource to be embedded is also a HAL resource.

In the ContentGrid application, this is mostly used for the entity-collection resource, where the page is the main resource, and all items on the page are embedded resources.

Link Relation Types work the same for embedded resources as they do for links.

An embedded resource should have a self link. The link attributes on the self-link of the embedded resource can be considered as the link attributes that would be present on a normal link to the embedded resource.

{
  "_embedded": {
    "item": [
      {
        "id": "62282aba-13bc-11f1-9a7d-ebcebd0bcf11",
        [...]
        "_links": {
          "self": {
            "href": "/invoices/62282aba-13bc-11f1-9a7d-ebcebd0bcf11",
            "title": "Invoice 62282aba-13bc-11f1-9a7d-ebcebd0bcf11"
          },
          [...]
        }
      }
    ]
  },
  [...]
}

{
  "_links": {
    "item": [
      {
        "href": "/invoices/62282aba-13bc-11f1-9a7d-ebcebd0bcf11",
        "title": "Invoice 62282aba-13bc-11f1-9a7d-ebcebd0bcf11"
      },
    ]
  },
  [...]
}

Working with HAL-FORMS Templates

Where HAL links describe related resources, HAL-FORMS templates describe the operations available on the resource.

HAL-FORMS are described in their own specification. ContentGrid adds additional functionality to the base specification, described in HAL-FORMS extensions.

The keys in _templates tell you what forms are available.

ContentGrid standardizes the following keys:

HAL-FORMS Extensions

ContentGrid extends the HAL-FORMS specification with support for nested JSON objects, additional body encodings (multipart/form-data and text/uri-list), and extended options element behavior.

See the HAL-FORMS Extensions reference for the full specification.

Navigating Collections

The entity-collection resource provides HAL links that can be used pagination.

Pagination uses the standard IANA-registered link relation types for their purpose:

• first: First page of results (may be absent if you’re already on the first page)
• prev: Previous page of results (absent when on the first page)
• next: Next page of results (absent when on the last page)
• self: Current page

To navigate through pages, follow the next link until it’s absent. The cursors in these links are opaque values managed by the server - don’t try to parse or construct them yourself.

Discovering the API Structure

Start at the entities-root resource to discover the entire API.

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

GET / HTTP/1.1
Authorization: Bearer $TOKEN

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json

{
  "_links": {
    "self": {
      "href": "https://app.contentgrid.example/"
    },
    "profile": {
      "href": "https://app.contentgrid.example/profile"
    },
    "cg:entity": [
      {
        "href": "https://app.contentgrid.example/invoices",
        "title": "Invoices",
        "name": "invoice"
      },
      {
        "href": "https://app.contentgrid.example/suppliers",
        "title": "Suppliers",
        "name": "supplier"
      }
    ],
    "curies": [
      {
        "href": "https://contentgrid.cloud/rels/contentgrid/{rel}",
        "name": "cg",
        "templated": true
      }
    ]
  }
}

The root resource contains cg:entity links to all entity collections in your data model. Use these to discover what entities are available without hardcoding entity names.

Alternatively, follow the profile link to arrive at the profile-root, and follow the cg:entity links there to arrive at the entity-profiles for every entity in your data model.

Using Entity Profiles

Entity profiles provide machine-readable metadata about entity types in a ContentGrid application. They describe the attributes, relations, constraints, and available operations for each entity type.

The entity-profile supports content negotiation between two formats:

Profiles are linked from:

• The profile-root resource (/profile) via cg:entity links
• entity-collection resources via the profile link relation type

HAL-FORMS Format

The HAL-FORMS profile format is the richest representation. It describes the full model of an entity type, its attributes and relations, and provides search and create-form templates.

The full HAL-FORMS entity profile format is documented in the Entity Profiles: HAL-FORMS Format reference.

JSON Schema Format

Request a profile with Accept: application/schema+json to receive a JSON Schema (2020-12) representation of the entity type.

In this format:

• Attributes are mapped to properties with their corresponding JSON Schema types
• Relations are represented as properties with "format": "uri"
• Content attributes use "$ref": "#/$defs/content", with sub-attribute properties defined in $defs.content
• Required attributes are listed in the required array

curl -i https://$APP_ID.$REGION.contentgrid.cloud/profile/invoices   \
    -H 'Accept: application/schema+json'   \
    -H "Authorization: Bearer $TOKEN"

GET /profile/invoices HTTP/1.1
Authorization: Bearer $TOKEN
Accept: application/schema+json

HTTP/1.1 200 OK
Content-Type: application/schema+json

{
  "title": "Invoice",
  "$defs": {
    "content": {
      "type": "object",
      "properties": {
        "filename": {
          "title": "Filename",
          "readOnly": false,
          "type": "string"
        },
        "length": {
          "title": "Size",
          "description": "File size in bytes",
          "readOnly": true,
          "type": "integer"
        },
        "mimetype": {
          "title": "Mimetype",
          "description": "Technical indicator of the type of the file",
          "readOnly": false,
          "type": "string"
        }
      }
    }
  },
  "properties": {
    "pay_before": {
      "title": "Pay before",
      "readOnly": false,
      "type": "string",
      "format": "date"
    },
    "total_amount": {
      "title": "Total amount",
      "readOnly": false,
      "type": "number"
    },
    "document": {
      "title": "Document",
      "readOnly": false,
      "$ref": "#/$defs/content"
    },
    "supplier": {
      "title": "Supplier",
      "readOnly": false,
      "type": "string",
      "format": "uri"
    },
    "received": {
      "title": "Received",
      "readOnly": false,
      "type": "string",
      "format": "date"
    },
    "id": {
      "title": "id",
      "readOnly": true,
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "received",
    "pay_before",
    "total_amount"
  ],
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Error handling

The ContentGrid REST API uses the standard HTTP status codes to signal errors.

RFC9457 Problem Details are used to provide additional information about the error condition.

HTTP Status Codes

The ContentGrid Application API uses standard HTTP status codes to indicate the success or failure of API requests.

These status codes provide high-level information about what happened with your request, and are generically described in RFC9110.

Successful Responses (2xx)

• 200 OK: The request succeeded. The response body contains the requested resource or data.
• 201 Created: A new resource was successfully created. The Location header contains the URL of the newly created resource.
• 204 No Content: The request succeeded but there is no response body. This is typically returned after successful updates or deletions.

Redirection Responses (3xx)

• 302 Found: The resource is temporarily available at a different URI. The Location header contains the URI where the resource can be found. This is commonly used when accessing relations.

Client Error Responses (4xx)

• 400 Bad Request: The request is malformed or contains invalid data. The response body may contain a problem detail explaining what went wrong if the request is sufficiently syntactically valid to be able to be processed.
• 401 Unauthorized: The request lacks valid authentication credentials.
• 403 Forbidden: The server understood the request but refuses to authorize it. This occurs when you don’t have permission to perform the requested operation.
• 404 Not Found: The requested resource does not exist. This could be an entity that doesn’t exist, an empty relation, or an unknown endpoint.
• 409 Conflict: The request conflicts with the current state of the resource. This occurs with unique constraint violations or when trying to delete an entity that is still referenced by required relations.
• 412 Precondition Failed: The condition specified in the request headers (If-Match or If-None-Match) was not met. This typically occurs when using optimistic locking and the entity has been modified by another request.
• 415 Unsupported Media Type: The Content-Type header specifies a media type that the server doesn’t support for this endpoint.

Server Error Responses (5xx)

• 500 Internal Server Error: An unexpected error occurred on the server. Contact support if this persists.

Problem Details (RFC 9457)

When an error occurs (4xx or 5xx status codes), the API returns a standardized error response using the RFC9457 Problem Details format. This provides a consistent, machine-readable way to communicate error information.

Problem Detail Structure

All error responses have Content-Type: application/problem+json and include these standard fields:

• type (string): A URI identifying the problem type (e.g., https://contentgrid.cloud/problems/not-found/entity-item)
• title (string): A short, human-readable summary of the problem type
• detail (string): A human-readable explanation specific to this occurrence of the problem
• status (number): The HTTP status code for this problem
• Additional properties: Problem-specific fields that provide more context

curl -i -X PATCH https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE_ID   \
    --json "{\"pay_before\": \"2024-08-13\"}"   \
    -H 'If-Match: "outdated-version"'   \
    -H "Authorization: Bearer $TOKEN"

PATCH /invoices/$INVOICE_ID HTTP/1.1
Authorization: Bearer $TOKEN
If-Match: "outdated-version"
Content-Type: application/json

{"pay_before": "2024-08-13"}

HTTP/1.1 412 Precondition Failed
Content-Type: application/problem+json

{
  "type": "https://contentgrid.cloud/problems/unsatisfied-version",
  "title": "Object has changed",
  "detail": "Requested version constraint 'is any of [exactly 'outdated-version']' can not be satisfied (actual version exactly '1r061qt')",
  "status": 412,
  "actual_version": "1r061qt"
}

Problem Types Reference

For a complete catalog of all problem types returned by the ContentGrid API, see the Problem Types reference.

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.

{
  "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.

{
  "_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:

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).

Link Relation Types

Links express a relation between the resource they appear on (the link context), and the link target. The link relation type (RFC8288 Sec 3.3) determines the kind of relation between the link context and the link target.

Next to the standard link relation types, which are to be interpreted with their standardized meaning, ContentGrid defines following extension link relation types:

CURIEs

CURIEs (Compact URIs) are a shorthand notation for extension link relation types.

They are used as defined in the HAL specification. The curies link relation provides expansion templates.

Before comparing a link relation, a CURIE must be expanded into the full URI.

{
  [...]
  "_links": {
    "self": {
      "href": "https://example.com/users/123"
    },
    "cg:content": [
      {
        "name": "profile_picture",
        "href": "https://example.com/users/123/picture"
      }
    ],
    "https://contentgrid.cloud/rels/contentgrid/relation": [
      {
        "name": "friends",
        "href": "https://example.com/users/123/friends"
      }
    ],
    "[example:curied-link]": {
      "href": "https://example.com/dahl-curry"
    },
    "unregistered:curie": {
      "href": "https://example.com/unregistered-curie"
    },
    "curies": [
      {
        "name": "cg",
        "href": "https://contentgrid.cloud/rels/contentgrid/{rel}",
        "template": true
      },
      {
        "name": "example",
        "href": "https://example.com/relations/{rel}",
        "template": true
      }
    ]
  }
}

{
  [...]
  "_links": {
    "self": {
      "href": "https://example.com/users/123"
    },
    "https://contentgrid.cloud/rels/contentgrid/content": [
      {
        "name": "profile_picture",
        "href": "https://example.com/users/123/picture"
      }
    ],
    "https://contentgrid.cloud/rels/contentgrid/relation": [
      {
        "name": "friends",
        "href": "https://example.com/users/123/friends"
      }
    ],
    "https://example.com/relations/curied-link": {
      "href": "https://example.com/dahl-curry"
    }
  }
}

Problem Types

The ContentGrid REST API uses the standard HTTP status codes to signal errors.

RFC9457 Problem Details are used to provide additional information about the error condition.

This reference describes all Problem Detail types that can be returned by the ContentGrid Application REST API.

Unless specified otherwise, the HTTP Status code for problems will be 400 Bad Request.

Input Validation Problems

These problems occur when the data you provide in the request body doesn’t meet the requirements.

Input validation problems are always represented by the a Problem Detail with type https://contentgrid.cloud/problems/input/validation.

input/validation

https://contentgrid.cloud/problems/input/validation

The ProblemDetail contains an additional property, errors, which contains a list of validation errors.

Each validation error has the same structure as a ProblemDetail, with as type one of the subtypes listed below. Each validation error also has a field property, which refers to the specific input field for which validation failed with a property path.

{
  "type": "https://contentgrid.cloud/problems/input/validation",
  "title": "Validation error",
  "detail": "2 validation errors",
  "status": 400,
  "errors": [
    {
      "type": "https://contentgrid.cloud/problems/input/validation/required",
      "title": "Mandatory field",
      "detail": "A value must be present, but it is missing or empty",
      "field": "pay_before"
    },
    {
      "type": "https://contentgrid.cloud/problems/input/validation/type",
      "title": "Invalid data type",
      "detail": "Expected value of type date, but got decimal",
      "field": "received",
      "expected_type": "date",
      "actual_type": "decimal"
    }
  ]
}

input/validation/type

https://contentgrid.cloud/problems/input/validation/type

The value provided has the wrong data type.

A data type error can happen when handling a JSON or a multipart form body.

For example:

• sending a decimal instead of a long
• sending a JSON array instead of a single value
• sending a JSON object instead of a single value
• repeating the same multipart form field multiple times instead of once
• sending a multipart file instead of a normal form field

Additional Properties:

• expected_type (string): The technical name of the expected data type
• actual_type (string): The technical name of the actual data type received

input/validation/type/format

https://contentgrid.cloud/problems/input/validation/type/format

The value is of the correct type, but it doesn’t match the expected format.

In this case the type is correct (usually a string), but the type (e.g. date, timestamp, relation link) requires a specific format, which was not fulfilled.

For example:

• sending an arbitrary string instead of a date or timestamp in RFC3339 format
• sending a link to an entity that is of the wrong type for this relation

Additional Properties:

• expected_type (string): The expected data type
• format_error (string): Description of the format error

input/validation/no-content

https://contentgrid.cloud/problems/input/validation/no-content

A content attribute can not be set when there is no content present.

This happens when writing to nested fields in a content attribute, but there is no content present.

It is only valid to change content fields (e.g. set filename or mimetype) when an actual file is present.

input/validation/required

https://contentgrid.cloud/problems/input/validation/required

A required field is set to null.

input/validation/duplicate

https://contentgrid.cloud/problems/input/validation/duplicate

The value provided for an attribute must be unique, but an other entity item already uses this value.

Additional Properties:

• conflicting_item (string): URL of the entity that already has this value

input/validation/allowed-values

https://contentgrid.cloud/problems/input/validation/allowed-values

The value is not one of the allowed values.

The possible values for an attribute can be restricted to a list of allowed values. It is then not allowed to use any other value.

Additional Properties:

• allowed_values (list): A list of all the values that are allowed for the field

input/validation/missing-relation-target

https://contentgrid.cloud/problems/input/validation/missing-relation-target

An entity-item that is being linked to a relation does not exist.

Additional Properties:

• missing_item (string): URL of the entity-item that does not exist

Query Parameter Problems

These problems occur when request query parameters don’t meet the requirements.

Contrary to input validation, only a single problem is reported at a time.

invalid-query-parameter/filter/format

https://contentgrid.cloud/problems/invalid-query-parameter/filter/format

Query parameter values are always strings. For some operations, they need to be converted to a certain type (e.g. to a number for a greater-than filter, or to a timestamp for a before filter).

If the value can not be converted, this problem is reported

Additional Properties:

• query_parameter (string): The name of the query parameter
• expected_type (string): The expected data type
• format_error (string): Description of the format error
• additional_errors (array): List of additional filter format errors, when multiple occur at the same time.

invalid-query-parameter/sort/format

https://contentgrid.cloud/problems/invalid-query-parameter/sort/format

The _sort query parameter is malformed and doesn’t match the expected format.

The expected format for sorting is <attribute_name>,asc or <attribute_name>,desc for ascending and descending sorting. Other formats are invalid.

Additional Properties:

• query_parameter (string): The name of the query parameter (always _sort)
• format_error (string): Description of the format error

invalid-query-parameter/sort/target

https://contentgrid.cloud/problems/invalid-query-parameter/sort/target

The _sort query parameter references a sort target that doesn’t exist, or on which sorting is not possible.

Sorting is only possible on attributes that are indexed in a way that supports sorting.

Additional Properties:

• query_parameter (string): The name of the query parameter (always _sort)
• target_name (string): The sort target name which couldn’t be sorted on

invalid-query-parameter/pagination

https://contentgrid.cloud/problems/invalid-query-parameter/pagination

A pagination-related query parameter (_cursor or _limit) is invalid.

• The _limit field value must be 1-1000.
• The _cursor field value should never be manually constructed; use the next_cursor and prev_cursor values from API responses (or follow the HAL links).

Additional Properties:

• query_parameter (string): The name of the query parameter
• format_error (string): Description of the format error

General request problems

These problems occur when there is something wrong with the request in general, in ways that are normally never encountered when integrating with ContentGrid.

They are still listed here for reference.

invalid-request/body

https://contentgrid.cloud/problems/invalid-request/body

The request body is malformed and can not be parsed.

Note that depending on the content-type, a more specific problem detail may be returned (e.g. for json or uri-list formats)

invalid-request/body/json

https://contentgrid.cloud/problems/invalid-request/body/json

The request body contains malformed JSON that can not be parsed.

invalid-request/body/uri-list

https://contentgrid.cloud/problems/invalid-request/body/uri-list

The request body contains a malformed URI list that can not be parsed.

invalid-request/body/single-link

https://contentgrid.cloud/problems/invalid-request/body/single-link

The request body does not have exactly one link.

This problem occurs when sending a request containing multiple (or zero) links to a to-one relation. A PUT on a to-one relation must contain exactly one link.

invalid-request/required-header

https://contentgrid.cloud/problems/invalid-request/required-header

A required HTTP header is missing from the request.

Additional Properties:

• header (string): The name of the header that is missing

invalid-request/forbidden-header

https://contentgrid.cloud/problems/invalid-request/forbidden-header

A HTTP Header is present that is not allowed

Additional Properties:

• header (string): The name of the header that is not allowed

invalid-request/invalid-header

https://contentgrid.cloud/problems/invalid-request/invalid-header

A HTTP Header has a value that is not syntatically valid

Additional Properties:

• header (string): The name of the header that is not valid

Version Conflict Problems

unsatisfied-version

https://contentgrid.cloud/problems/unsatisfied-version

The entity version specified in the If-Match and/or If-None-Match headers doesn’t match the current version.

This error can happen when using conditional requests, and the entity is modified by another request between get and update.

HTTP Status: 412 Precondition Failed

Additional Properties:

• actual_version (string): The current version of the entity

Not Found Problems

These problems have HTTP status code 404 Not Found.

Different problem types are used to help distinguish between typos in URLs and entity items that may not be present anymore.

not-found/endpoint

https://contentgrid.cloud/problems/not-found/endpoint

The requested API endpoint does not exist.

This problem type indicates an error in the fixed parts of the URL: in the entity, relation or attribute name.

Check the URL for typos. Ensure you’re using the correct entity type name and that the entity type exists in your data model. If the URL used to work, check that the entity/attribute/relation definition was not renamed or deleted in a newer version of the data model.

not-found/entity-item

https://contentgrid.cloud/problems/not-found/entity-item

No entity was found with the specified id. The entity may have been deleted, or may have never existed.

not-found/relation-item

https://contentgrid.cloud/problems/not-found/relation-item

The relation does not contain the requested entity-item.

This can happen for all relation types:

• to-one relations: When nothing is linked, a GET or DELETE on the relation resource will result in this error
• to-many relations: When a specific item is not linked, a GET or DELETE on the relation-item resource will result in this error

Integrity Problems

These problems occur when an operation would violate data integrity constraints.

Unless specified otherwise, integrity problems will use the 409 Conflict HTTP status code.

integrity/blind-relation-overwrite

https://contentgrid.cloud/problems/integrity/blind-relation-overwrite

In a to-one relation, the target entity is already referenced by another entity. The operation would silently overwrite that reference without ability to apply proper concurrency control.

Additional Properties:

• new_item (string): URL of the entity you’re trying to link
• new_relation (string): URL of the relation you’re trying to set
• existing_item (string): URL of the entity currently linked
• existing_relation (string): URL of the existing relation
• target_item (string): URL of the target entity
• target_relation (string): URL of the inverse relation (if available)
• additional_errors (array): List of additional blind relation overwrite errors, when multiple occur at the same time.

How to Fix: This is a safety mechanism to prevent data loss. You have several options:

1. Unlink the existing relation first (DELETE on existing_relation), then create the new link
2. Use the target entity’s relation endpoint to manage the link, if available
3. Review your data model - you may need a to-many relation instead of to-one

integrity/required-relation

https://contentgrid.cloud/problems/integrity/required-relation

This problem indicates that the entity-item is referenced in a required relation

It can happen when:

1. trying to delete the entity-item, and it is referenced by any required relation
2. trying to unlink the entity-item from a relation, and the other side of the relation is required.

Additional Properties:

• affected_relation (string): URL of the relation that requires this entity

How to Fix: Before deleting or unlinking the entity, either:

1. Delete the referencing entity first
2. Update the referencing entity to link to a different entity
3. If the relation should be optional in your data model, update your model definition

HAL-FORMS Extensions

The HAL-FORMS specification defines request body encodings for application/json and application/x-www-form-urlencoded.

ContentGrid extends the HAL-FORMS specification:

• to allow construction of nested JSON objects for application/json request body encoding
• to define request body encodings for multipart/form-data and text/uri-list
• the options element is extended to define the behavior of a link with a mediatype of application/hal+json and application/prs.hal-forms+json

Body encoding for application/json

To encode a nested JSON object, the property name will be interpreted as a property path.

Properties for which no value is present are not taken into account for serialization purposes.

{
  "contentType": "application/json",
  "properties": [
    {
      "name": "received",
      "prompt": "Received",
      "required": true,
      "type": "datetime"
    },
    {
      "name": "document.mimetype",
      "prompt": "Document mimetype",
      "type": "text"
    },
    {
      "name": "document.filename",
      "prompt": "Document filename",
      "type": "text"
    },
    {
      "name": "pay_before",
      "prompt": "Pay before",
      "required": true,
      "type": "datetime"
    },
    {
      "name": "total_amount",
      "prompt": "Total amount",
      "required": true,
      "type": "number"
    }
  ]
}

{
  "received": "2024-05-08T14:58:23Z",
  "document": {
      "mimetype": "text/plain",
      "filename": "example.txt"
  },
  "pay_before": "2024-06-08T00:00:00Z",
  "total_amount": 14.58
}

Body encoding for multipart/form-data

When sending bodies encoded as multipart/form-data, bodies SHOULD be encoded according to the WhatWG HTML standard.

Body encoded for text/uri-list

When sending bodies encoded as text/uri-list, the HAL-FORMS template MUST only contain a single property of type url.

Only the value (or values if the property is multi-value) of the property is part of the request body, in accordance to the text/uri-list mime type.

Multi-valued properties are serialized by having each value on a separate line.

{
  "contentType": "text/uri-list",
  "properties": [
    {
      "name": "supplier",
      "type": "url"
    }
  ]
}

http://example.com/example-path?q=abc

Extension for options element

The options element contains an enumerated list of possible values for a property.

When the options element contains a link attribute, the possible values are to be retrieved from a remote HTTP resource.

The link attribute has following child-attributes, with the same meaning as the HAL Link Object:

• href
• type
• templated
• profile

The behavior of the options element promptField and valueField attributes are dependent on the content-type of the remote HTTP resource. The type attribute may be used as a hint for the content-type of the remote HTTP resource, but the actual content-type of the response is authoritative.

{
  "name": "supplier",
  "options": {
    "link": {
      "href": "https://app.contentgrid.example/suppliers"
    }
  }
}

["Fedex","UPS","DHL"]

[
  {"prompt" : "Federal Express", "value" : "FedEx"},
  {"prompt" : "United Parcel Service", "value" : "UPS"},
  {"prompt" : "DHL Express", "value" : "DHL"}
]

Fedex
UPS
DHL

Federal Express,FedEx
United Parcel Service,UPS
DHL Express,DHL

{
  "_embedded": {
    "item": [
      {
        "name": "Federal Express",
        "_links": {
          "self": {
            "href": "https://app.contentgrid.example/suppliers/FedEx"
          }
        }
      },
      {
        "name": "United Parcel Service",
        "_links": {
          "self": {
            "href": "https://app.contentgrid.example/suppliers/UPS"
          }
        }
      }
    ]
  },
  "_links": {
    "next": {
      "href":  "https:/app.contentgrid.example/suppliers?page=2"
    }
  }
}

{
  "_embedded": {
    "item": [
      {
        "name": "DHL Express",
        "_links": {
          "self": {
            "href": "https://app.contentgrid.example/suppliers/DHL"
          }
        }
      }
    ]
  },
  "_links": {
    "prev": {
      "href":  "https:/app.contentgrid.example/suppliers?page=1"
    }
  }
}

Property path

A property path is used to reference fields in nested JSON objects.

The property path is built by separating JSON fields with .. e.g. document.filename will be serialized as a top-level field document which is assigned to an object with a filename field.

Entity Profile: HAL format

The HAL profile format describes the model of an entity type, its attributes and relations.

It also provides the search and create-form HAL-FORMS templates, which describe how to search and create new items of this type.

Link Relation Types

The entity profile uses standard link relation types and ContentGrid-specific extension link relation types. See the Link Relation Types reference for general information on link relation types and CURIEs.

The entity profile introduces the blueprint CURIE prefix (https://contentgrid.cloud/rels/blueprint/{rel}) for the following link relation types:

Entity Profile Fields

The top-level entity profile resource contains:

The entity profile also contains embedded HAL resources:

• blueprint:attribute: A list of the attributes that are present on the entity
• blueprint:relation: A list of the relations that are present on the entity

The entity profile contains HAL links:

curl -i https://$APP_ID.$REGION.contentgrid.cloud/profile/invoices   \
    -H 'Accept: application/prs.hal-forms+json'   \
    -H "Authorization: Bearer $TOKEN"

GET /profile/invoices HTTP/1.1
Authorization: Bearer $TOKEN
Accept: application/prs.hal-forms+json

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json

{
  "name": "invoice",
  "title": "Invoice",
  "description": null,
  "_embedded": {
    "blueprint:attribute": [...],
    "blueprint:relation": [...]
  },
  "_links": {
    "self": {
      "href": "https://app.contentgrid.example/profile/invoices",
      "title": "Invoice"
    },
    "describes": [
      {
        "href": "https://app.contentgrid.example/invoices",
        "title": "Invoices",
        "profile": "https://app.contentgrid.example/profile/invoices",
        "name": "collection"
      },
      {
        "href": "https://app.contentgrid.example/invoices/{id}",
        "title": "Invoice",
        "name": "item",
        "templated": true
      }
    ],
    "curies": [
      {
        "href": "https://contentgrid.cloud/rels/contentgrid/{rel}",
        "name": "cg",
        "templated": true
      },
      {
        "href": "https://contentgrid.cloud/rels/blueprint/{rel}",
        "name": "blueprint",
        "templated": true
      }
    ]
  },
  "_templates": {
    "search": {...},
    "create-form": {...}
  }
}

Embedded Resources

The entity profile contains embedded resources that describe the entity’s attributes and relations.

Attribute (blueprint:attribute)

Entity attributes are embedded resources in the entity profile under the link relation blueprint:attribute.

Each attribute itself contains embedded resources, describing details about the attribute:

• blueprint:constraint — constraints on this attribute
• blueprint:search-param — search parameters available for this attribute
• blueprint:attribute — sub-attributes for structured types

{
  "name": "received",
  "title": "Received",
  "type": "date",
  "description": null,
  "readOnly": false,
  "required": true,
  "_embedded": {
    "blueprint:constraint": [
      {
        "type": "required"
      }
    ],
  }
}

Sub-attributes

Attributes with type: "object" (such as content attributes) can contain nested blueprint:attribute sub-attributes. Sub-attributes have the same structure as top-level attributes, recursively.

{
  "name": "document",
  "title": "Document",
  "type": "object",
  "description": null,
  "readOnly": false,
  "required": false,
  "_embedded": {
    "blueprint:attribute": [
      {
        "name": "filename",
        "title": "Filename",
        "type": "string",
        "description": null,
        "readOnly": false,
        "required": false
      },
      {
        "name": "mimetype",
        "title": "Mimetype",
        "type": "string",
        "description": "Technical indicator of the type of the file",
        "readOnly": false,
        "required": false
      },
      {
        "name": "length",
        "title": "Size",
        "type": "long",
        "description": "File size in bytes",
        "readOnly": true,
        "required": false
      }
    ]
  }
}

Constraint (blueprint:constraint)

Constraints are embedded in an attribute under the link relation blueprint:constraint.

Following constraint types are supported:

Search Parameter (blueprint:search-param)

Search parameters are embedded in an attribute under the link relation blueprint:search-param. They describe the query parameters that can be used to filter on this attribute in the search template.

Following search parameter types are supported:

{
  "name": "pay_before",
  "title": "Pay before",
  "type": "date",
  "description": null,
  "readOnly": false,
  "required": true,
  "_embedded": {
    "blueprint:search-param": [
      {
        "name": "pay_before",
        "title": "Pay before",
        "type": "exact-match"
      },
      {
        "name": "pay_before~after",
        "title": "Pay before: After",
        "type": "greater-than"
      },
      [...]
    ]
}

Relation (blueprint:relation)

Relations are embedded in the entity profile under blueprint:relation.

Each relation has a blueprint:target-entity link, referencing to the profile of the target entity type.

{
  "name": "supplier",
  "title": "Supplier",
  "description": null,
  "many_source_per_target": true,
  "many_target_per_source": false,
  "required": false,
  "_links": {
    "blueprint:target-entity": {
      "href": "https://app.contentgrid.example/profile/suppliers",
      "title": "Supplier"
    }
  }
}

Templates

The entity profile provides HAL-FORMS templates that describe how to search and create entities of this type. See HAL-FORMS extensions for additional details on the extensions used.

search Template

The search template describes how to filter and sort the entity collection.

Search template properties are composed from 3 sources:

• search parameters defined on attributes
• Cross relation search parameters, where the search parameters from the relation target entity are prefixed by the relation name and a dot (e.g. supplier.name)
• Special properties: _sort

The _sort property is a special property with a list of options. Next to the standard options as defined in HAL-FORMS, each option has property and direction fields. These additional fields can be used to programmatically select an option for a particular attribute and a particular sorting direction without having to resort to string manipulation.

{
  "_templates": {
    "search": {
      "method": "GET",
      "target": "https://app.contentgrid.example/invoices",
      "properties": [
        {
          "name": "pay_before",
          "prompt": "Pay before",
          "type": "date"
        },
        [...]
        {
          "name": "supplier.name",
          "prompt": "Supplier: Name",
          "type": "text"
        },
        {
          "name": "_sort",
          "prompt": "Sort",
          "type": "text",
          "options": {
            "minItems": 0,
            "promptField": "prompt",
            "valueField": "value",
            "inline": [
              {
                "property": "pay_before",
                "direction": "asc",
                "prompt": "Pay before ascending",
                "value": "pay_before,asc"
              },
              {
                "property": "pay_before",
                "direction": "desc",
                "prompt": "Pay before descending",
                "value": "pay_before,desc"
              },
              {
                "property": "total_amount",
                "direction": "asc",
                "prompt": "Total amount 0\u21929",
                "value": "total_amount,asc"
              },
              {
                "property": "total_amount",
                "direction": "desc",
                "prompt": "Total amount 9\u21920",
                "value": "total_amount,desc"
              }
            ]
          }
        }
      ]
    }
  }
}

create-form Template

The create-form template describes how to create a new entity of this type.

Depending on whether content attributes are present, the form can use application/json or multipart/form-data content types.

The create form includes fields for both attributes and relations, following the HAL-FORMS extensions specification.

{
  "_templates": {
    "create-form": {
      "method": "POST",
      "target": "https://app.contentgrid.example/invoices",
      "contentType": "multipart/form-data",
      "properties": [
        {
          "name": "received",
          "prompt": "Received",
          "required": true,
          "type": "date"
        },
        {
          "name": "document",
          "prompt": "Document",
          "type": "file"
        },
        {
          "name": "pay_before",
          "prompt": "Pay before",
          "required": true,
          "type": "date"
        },
        {
          "name": "total_amount",
          "prompt": "Total amount",
          "required": true,
          "type": "number"
        },
        {
          "name": "supplier",
          "prompt": "Supplier",
          "type": "url",
          "options": {
            "link": {
              "href": "https://app.contentgrid.example/suppliers",
              "title": "Suppliers"
            },
            "minItems": 0,
            "maxItems": 1,
            "valueField": "/_links/self/href"
          }
        }
      ]
    }
  }
}