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

// 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

/*
 * 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:

Last updated