Relations

What data is linked to what other data. Allows you to assign authors to articles, products to sales, and whatever other structures you can think of.

Endpoints
   GET /:project/relations
   GET /:project/relations/:id
  POST /:project/relations
 PATCH /:project/relations/:id
DELETE /:project/relations/:id

The Relation Object

id integer

Unique identifier for the relation.

collection_many string

Collection that has the field that holds the foreign key.

field_many string

Foreign key. Field that holds the primary key of the related collection.

collection_one string

Collection on the one side of the relationship.

field_one string

Alias column that serves as the one side of the relationship.

junction_field string

Field on the junction table that holds the primary key of the related collection.

Relation Object
{
  "id": 1,
  "collection_many": "directus_activity",
  "field_many": "action_by",
  "collection_one": "directus_users",
  "field_one": null,
  "junction_field": null
}

List the Relations

List the relations.

Parameters

project required

The project you're targetting.

Query

fields optional

Control what fields are being returned in the object. Learn more

limit optional

A limit on the number of objects that are returned. Default is 200. Learn more

offset optional

How many items to skip when fetching data. Default is 0. Learn more

page optional

Cursor for use in pagination. Often used in combination with limit. Learn more

sort optional

How to sort the returned items. Learn more

single optional

Return the result as if it was a single item. Useful for selecting a single item based on filters and search queries. Will force limit to be 1. Learn more

filter optional

Select items in collection by given conditions. Learn more

q optional

Filter by items that contain the given search query in one of their fields. Learn more

meta optional

What metadata to return in the response. Learn more

Returns

Returns an array of relation objects.

Endpoint
   GET /:project/relations
Response
{
  "data": [
    {
      "id": 1,
      "collection_many": "directus_activity",
      "field_many": "action_by",
      "collection_one": "directus_users",
      "field_one": null,
      "junction_field": null
    },
    { ... },
    { ... }
  ]
}

Retrieve a Relation

Retrieve a single relation by unique identifier.

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Query

fields optional

Control what fields are being returned in the object. Learn more

meta optional

What metadata to return in the response. Learn more

Returns

Returns the relation object for the given unique identifier.

Endpoint
   GET /:project/relations/:id
Response
{
  "data": {
    "id": 1,
    "collection_many": "directus_activity",
    "field_many": "action_by",
    "collection_one": "directus_users",
    "field_one": null,
    "junction_field": null
  }
}

Create a Relation

Create a new relation.

Parameters

project required

The project you're targetting.

Attributes

collection_many required

Collection that has the field that holds the foreign key.

field_many required

Foreign key. Field that holds the primary key of the related collection.

collection_one optional

Collection on the one side of the relationship.

field_one optional

Alias column that serves as the one side of the relationship.

junction_field optional

Field on the junction table that holds the primary key of the related collection.

Query

fields optional

Control what fields are being returned in the object. Learn more

meta optional

What metadata to return in the response. Learn more

Returns

Returns the relation object for the relation that was just created.

Endpoint
  POST /:project/relations
Request
{
  "collection_many": "articles",
  "field_many": "author",
  "collection_one": "authors",
  "field_one": "books"
}
Response
{
  "data": {
    "id": 15,
    "collection_many": "articles",
    "field_many": "author",
    "collection_one": "authors",
    "field_one": "books",
    "junction_field": null
  }
}

Update a Relation

Update an existing relation

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Attributes

collection_many optional

Collection that has the field that holds the foreign key.

field_many optional

Foreign key. Field that holds the primary key of the related collection.

collection_one optional

Collection on the one side of the relationship.

field_one optional

Alias column that serves as the one side of the relationship.

junction_field optional

Field on the junction table that holds the primary key of the related collection.

Query

fields optional

Control what fields are being returned in the object. Learn more

meta optional

What metadata to return in the response. Learn more

Returns

Returns the relation object for the relation that was just updated.

Endpoint
 PATCH /:project/relations/:id
Request
{
  "field_one": "books"
}
Response
{
  "data": {
    "id": 15,
    "collection_many": "articles",
    "field_many": "author",
    "collection_one": "authors",
    "field_one": "books",
    "junction_field": null
  }
}

Delete a Relation

Delete an existing relation.

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Returns

Returns an empty body with HTTP status 204

Endpoint
DELETE /:project/relations/:id