diff --git a/content/guides/04.connect/3.query-parameters.md b/content/guides/04.connect/3.query-parameters.md index 7ee7b17e..e37d5c1d 100644 --- a/content/guides/04.connect/3.query-parameters.md +++ b/content/guides/04.connect/3.query-parameters.md @@ -560,7 +560,7 @@ Saves the API response to a file. Valid values are `csv`, `json`, `xml`, `yaml`. ## Version -Queries a version of a record by version key when [content versioning](/guides/content/content-versioning) is enabled on a collection. Applies only to single item retrieval. +Queries a version of a record by version key when [content versioning](/guides/content/content-versioning) is enabled on a collection. ::callout{icon="i-lucide-info"} **Reserved version keys** @@ -569,11 +569,18 @@ The keys `published` and `draft` are reserved. Use `published` (or `main` for ba ::code-group -```http [GET /items/posts/1] -?version=v1 +```http [REST] +// Both item lists and single items are supported: + +GET /items/posts + ?version=v1 + +GET /items/posts/1 + ?version=v1 ``` ```graphql [GraphQL] +# Only supported on single item and singleton reads, not collection-level queries. query { posts_by_id(id: 1, version: "v1") { id @@ -582,11 +589,17 @@ query { ``` ```js [SDK] -import { createDirectus, rest, readItem } from "@directus/sdk"; +import { createDirectus, rest, readItem, readItems } from "@directus/sdk"; const directus = createDirectus("https://directus.example.com").with(rest()); const result = await directus.request( - readItem("posts", { + readItems("posts", { + version: "v1", + }), +); + +const item = await directus.request( + readItem("posts", 1, { version: "v1", }), ); @@ -594,15 +607,26 @@ const result = await directus.request( :: +### Version Meta + +Versioned items include an additional `$meta` field in the response. It contains `version_id`, which is the `id` of the record in `directus_versions`, not its `key`. When a version has no saved changes or could not be applied to the item, `$meta` also contains `delta`, plus an `error` object in the failure case. + +### Item-less Drafts + +[Item-less drafts](/guides/content/content-versioning#creating-new-items-as-drafts) appear in a list response with a `null` primary key, as the item does not exist in the collection yet. Likewise, any relational records created as part of the draft version also have `null` values. + +To read related records that already existed, request nested fields, for example `&fields=*,tags.*.*`{lang="http"}. + ## VersionRaw -Specifies to return relational delta changes as a [detailed output](https://directus.com/docs/guides/connect/relations#creating-updating-deleting) on a version record. +Specifies to return relational delta changes as a [detailed output](/guides/connect/relations#creating-updating-deleting) on a version record. Applies only to single item retrieval. ::code-group ```http [REST] GET /items/posts/1 - ?version=v1&versionRaw=true + ?version=v1 + &versionRaw=true ``` ```graphql [GraphQL] @@ -618,7 +642,7 @@ import { createDirectus, rest, readItem } from "@directus/sdk"; const directus = createDirectus("https://directus.example.com").with(rest()); const result = await directus.request( - readItem("posts", { + readItem("posts", 1, { version: "v1", versionRaw: true, }),