Includes

With the parameter includes you can aggregate relations for a document that were defined by relation fields for a content type.

Define a general number of included relation levels

GET https://api.cmft.io/v1/<repoName>/<endpoint>?includes=<level>

Path Parameters

Name	Type	Description
repoName	string	The API identifier of the repository
endpoint	string	The endpoint you'd like to query
include	number	The levels of includes

200

// Example for 'includes=1' (aggregate first level)
data: [
{
  "fields": {
    "title": "Roses are red",
    "author": {
      "meta": {
        "id": "323979853562951413",
        "contentType": "author"
      }
    }
  },
  "meta": {
    "id": "314159265358979323",
    "contentType": "poem",
    "repository": "123456789011121415",
    "revision": 1,
    "tags": [],
    "createdAt": "2018-01-01T00:00:00.000Z",
    "updatedAt": "2018-01-01T00:00:00.000Z"
  }
}
],
includes: [
  author: [
    {
      "fields": {
        "name": "Victor Hugo"
      },
      "meta": {
        "id": "323979853562951413",
        "contentType": "author",
        "repository": "123456789011121415",
        "revision": 1,
        "tags": [],
        "createdAt": "2018-01-01T00:00:00.000Z",
        "updatedAt": "2018-01-01T00:00:00.000Z"
      }
    }
  ]
]

A level of 1 would aggregate all relations, from all relation fields, of the first level. A level of 2 would also return all of the relations to those documents of the first level. The maximum number of levels is 5.

Include relations from specific fields

GET https://api.comft.io/v1/<repoName>/<endpoint>?includes[<field>]=1

Path Parameters

Name	Type	Description
repoName	string	The API identifier of the repository
endpoint	string	The endpoint you'd like to query
include	string	The field path you'd like to include

200

/*
 * Example for 'includes[*.fields.author]=1'
 * (aggregate the author field, specifically)
 */
 
data: [
{
  "fields": {
    "title": "Roses are red",
    "author": {
      "meta": {
        "id": "323979853562951413",
        "contentType": "author"
      }
    }
  },
  "meta": {
    "id": "314159265358979323",
    "contentType": "poem",
    "repository": "123456789011121415",
    "revision": 1,
    "tags": [],
    "createdAt": "2018-01-01T00:00:00.000Z",
    "updatedAt": "2018-01-01T00:00:00.000Z"
  }
}
],
includes: [
  author: [
    {
      "fields": {
        "name": "Victor Hugo"
      },
      "meta": {
        "id": "323979853562951413",
        "contentType": "author",
        "repository": "123456789011121415",
        "revision": 1,
        "tags": [],
        "createdAt": "2018-01-01T00:00:00.000Z",
        "updatedAt": "2018-01-01T00:00:00.000Z"
      }
    }
  ]
]

If you just want to include the relations from a single or multiple specific fields, you can define these fields in your query.

Notation

The notation for fields is similar to filters. You can either include a contentType as field prefix, or a wildcard (*).

includes[<contentType>.fields.<fieldName>]=1

or

includes[*.fields.<fieldName>]=1

To query multiple levels (relation of a relation...) with the field syntax, fields can be chained:

includes[<contentType>.fields.<fieldName>.fields.<fieldName>]=1

Field types

Field types which contain references are the following:

• relation field

• asset field

Embed Assets

From a technical perspective, assets are relations and by default they are treated like that.

But sometimes assets, for example images, can be seen as a piece of content that you want to be included within a document field. For this case, you can use the embedAssets parameter.

Notation

embedAssets=true

Examples

Find some examples on the includes example page:

pageIncludes