mirror of
https://github.com/directus/directus.git
synced 2026-02-05 14:25:05 -05:00
817ccf3620
* Add Quickstart Guide * Update installation * Remove unused files * Update support/backing * Tweaks in concepts * Setup file structure for API reference 2.0 * Setup page layout for reference * Add clean-urls plugin * getting started updates * Finish authentication rest * getting started updates * Render stylus in 2 spaces * Various * Various * Finish activity docs * Add collections reference * Add extension reference * concepts updates * Fields/tweaks * Add files doc * Add revisions * concepts docs * More api reference * Finish rest api reference (finally) * initial concepts * More things * Add assets api ref * Move sections from file to assets * Add environment variables * contributing docs * Add field transforms page * Left align table headers * concept links * Add API config * Fix mobile nav * Add migrating a project * doc link fixes Co-authored-by: Ben Haynes <ben@rngr.org>
339 lines
5.1 KiB
Markdown
339 lines
5.1 KiB
Markdown
---
|
|
pageClass: page-reference
|
|
---
|
|
|
|
# Relations
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
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.
|
|
|
|
</div>
|
|
<div class="right">
|
|
|
|
[[toc]]
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|
|
|
|
## The Relation Object
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
<div class="definitions">
|
|
|
|
`id` **integer**\
|
|
Primary key of the relation.
|
|
|
|
`many_collection` **string**\
|
|
Collection on the "many" side of the relation.
|
|
|
|
`many_field` **string**\
|
|
Field on the "many" side of the relation.
|
|
|
|
`one_collection` **string**\
|
|
Collection on the "one" side of the relation.
|
|
|
|
`one_field` **string**\
|
|
Field on the "one" side of the relation.
|
|
|
|
`one_collection_field` **string**\
|
|
In Many-to-Any type fields, this holds the field in the many collection that holds the name of the "one" collection.
|
|
|
|
`one_allowed_collections` **string**\
|
|
In Many-to-Any type fields, this holds a csv of collection names the user is allowed to use through the m2a relation.
|
|
|
|
`junction_field` **string**\
|
|
For Many-to-Many type fields, this holds the name of the field that "links" a many-to-one to a one-to-many, creating a many-to-many.
|
|
|
|
</div>
|
|
</div>
|
|
<div class="right">
|
|
|
|
```json
|
|
{
|
|
"id": 13,
|
|
"many_collection": "articles",
|
|
"many_field": "featured_image",
|
|
"one_collection": "directus_files",
|
|
"one_field": null,
|
|
"one_collection_field": null,
|
|
"one_allowed_collections": null,
|
|
"junction_field": null
|
|
}
|
|
```
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|
|
|
|
## List relations
|
|
|
|
List all relations that exist in Directus.
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
::: tip Permissions
|
|
|
|
The data returned in this endpoint will be filtered based on the user's permissions. For example, relations that apply
|
|
to a collection that the current user doesn't have access to are stripped out.
|
|
|
|
:::
|
|
|
|
### Query Parameters
|
|
|
|
Supports all [global query parameters](/reference/api/query).
|
|
|
|
### Returns
|
|
|
|
An array of up to [limit](/reference/api/query/#limit) [relation objects](#the-relation-object). If no items are
|
|
available, data will be an empty array.
|
|
|
|
</div>
|
|
<div class="right">
|
|
|
|
### `GET /relations`
|
|
|
|
```json
|
|
// Response
|
|
|
|
{
|
|
"data": [
|
|
{
|
|
"id": 13,
|
|
"many_collection": "articles",
|
|
"many_field": "featured_image",
|
|
"one_collection": "directus_files",
|
|
"one_field": null,
|
|
"one_collection_field": null,
|
|
"one_allowed_collections": null,
|
|
"junction_field": null
|
|
},
|
|
{...},
|
|
{...}
|
|
]
|
|
}
|
|
```
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|
|
|
|
## Retrieve a relation
|
|
|
|
List an existing relation by primary key.
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
### Query Parameters
|
|
|
|
Supports all [global query parameters](/reference/api/query).
|
|
|
|
### Returns
|
|
|
|
Returns the requested [relation object](#the-relation-object).
|
|
|
|
</div>
|
|
<div class="right">
|
|
|
|
### `GET /relations/:id`
|
|
|
|
```json
|
|
// Response
|
|
|
|
{
|
|
"data": {
|
|
"id": 13,
|
|
"many_collection": "articles",
|
|
"many_field": "featured_image",
|
|
"one_collection": "directus_files",
|
|
"one_field": null,
|
|
"one_collection_field": null,
|
|
"one_allowed_collections": null,
|
|
"junction_field": null
|
|
}
|
|
}
|
|
```
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|
|
|
|
## Create relation
|
|
|
|
Create one or more new relation(s).
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
### Query Parameters
|
|
|
|
Supports all [global query parameters](/reference/api/query).
|
|
|
|
### Request Body
|
|
|
|
A partial [relation object](#the-relation-object) or an array of partial [relation objects](#the-relation-object).
|
|
|
|
### Returns
|
|
|
|
Returns the [relation object](#the-relation-object) for the created relation.
|
|
|
|
</div>
|
|
<div class="right">
|
|
|
|
### `POST /relations`
|
|
|
|
```json
|
|
// Request
|
|
|
|
{
|
|
"many_collection": "articles",
|
|
"many_field": "featured_image",
|
|
"one_collection": "directus_files"
|
|
}
|
|
```
|
|
|
|
```json
|
|
// Response
|
|
|
|
{
|
|
"data": {
|
|
"id": 13,
|
|
"many_collection": "articles",
|
|
"many_field": "featured_image",
|
|
"one_collection": "directus_files",
|
|
"one_field": null,
|
|
"one_collection_field": null,
|
|
"one_allowed_collections": null,
|
|
"junction_field": null
|
|
}
|
|
}
|
|
```
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|
|
|
|
## Update relation
|
|
|
|
Update an existing relation.
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
### Query Parameters
|
|
|
|
Supports all [global query parameters](/reference/api/query).
|
|
|
|
### Request Body
|
|
|
|
A partial [relation object](#the-relation-object).
|
|
|
|
### Returns
|
|
|
|
Returns the [relation object](#the-relation-object) for the created relation.
|
|
|
|
</div>
|
|
<div class="right">
|
|
|
|
### `PATCH /relations/:id`
|
|
|
|
```json
|
|
// Request
|
|
|
|
{
|
|
"one_field": "articles"
|
|
}
|
|
```
|
|
|
|
```json
|
|
// Response
|
|
|
|
{
|
|
"data": {
|
|
"id": 13,
|
|
"many_collection": "articles",
|
|
"many_field": "featured_image",
|
|
"one_collection": "directus_files",
|
|
"one_field": "articles",
|
|
"one_collection_field": null,
|
|
"one_allowed_collections": null,
|
|
"junction_field": null
|
|
}
|
|
}
|
|
```
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|
|
|
|
## Delete relation
|
|
|
|
Delete an existing relation.
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
### Returns
|
|
|
|
Empty body.
|
|
|
|
</div>
|
|
<div class="right">
|
|
|
|
### `DELETE /relations/:id`
|
|
|
|
```json
|
|
// Empty Response
|
|
```
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|
|
|
|
## Delete Multiple relations
|
|
|
|
Delete multiple existing relations.
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
### Request Body
|
|
|
|
An array of relation primary keys
|
|
|
|
### Returns
|
|
|
|
Empty body.
|
|
|
|
</div>
|
|
<div class="right">
|
|
|
|
### `DELETE /relations`
|
|
|
|
```json
|
|
// Request
|
|
[15, 251, 810]
|
|
```
|
|
|
|
```json
|
|
// Empty Response
|
|
```
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|