Add Content Versioning Specs (#20150)

Co-authored-by: Pascal Jufer <pascal-jufer@bluewin.ch>

.changeset/orange-bobcats-repeat.md

@@ -0,0 +1,5 @@
+---
+'@directus/specs': patch
+---
+
+Added content versioning specs

packages/specs/src/components/collection.yaml

@@ -48,6 +48,10 @@ properties:
         type: string
         example: null
         nullable: true
+      versioning:
+        description: Whether or not Content Versioning is enabled for this collection.
+        type: boolean
+        example: false
       archive_field:
         description: What field holds the archive value.
         type: string

packages/specs/src/components/revision.yaml

@@ -41,3 +41,9 @@ properties:
     example: null
     type: integer
     nullable: true
+  version:
+    description: Associated version of this revision.
+    example: draft
+    oneOf:
+      - type: string
+      - $ref: '../openapi.yaml#/components/schemas/Versions'

packages/specs/src/components/version.yaml

@@ -0,0 +1,49 @@
+type: object
+x-collection: directus_versions
+properties:
+  id:
+    description: Primary key of the Content Version.
+    example: 63716273-0f29-4648-8a2a-2af2948f6f78
+    type: string
+  key:
+    description: Key of the Content Version, used as the value for the "version" query parameter.
+    example: draft
+    type: string
+  name:
+    description: Descriptive name of the Content Version.
+    example: My Draft
+    type: string
+  collection:
+    description: Name of the collection the Content Version is created on.
+    example: articles
+    oneOf:
+      - type: string
+      - $ref: '../openapi.yaml#/components/schemas/Collections'
+  item:
+    description: The item the Content Version is created on.
+    example: '168'
+    type: string
+  date_created:
+    description: When the Content Version was created.
+    type: string
+    example: '2022-05-11T13:14:52Z'
+    format: date-time
+    nullable: true
+  date_updated:
+    description: When the Content Version was updated.
+    type: string
+    example: '2022-05-11T13:14:53Z'
+    format: date-time
+    nullable: true
+  user_created:
+    description: User that created the Content Version.
+    example: 63716273-0f29-4648-8a2a-2af2948f6f78
+    oneOf:
+      - type: string
+      - $ref: '../openapi.yaml#/components/schemas/Users'
+  user_updated:
+    description: User that updated the Content Version.
+    example: 63716273-0f29-4648-8a2a-2af2948f6f78
+    oneOf:
+      - type: string
+      - $ref: '../openapi.yaml#/components/schemas/Users'

packages/specs/src/openapi.yaml

@@ -87,6 +87,11 @@ tags:
     x-collection: directus_users
   - name: Utilities
     description: Directus comes with various utility endpoints you can use to simplify your development flow.
+  - name: Versions
+    description:
+      Enables users to create unpublished copies of an item, modify them independently from the main version, and
+      promote them to become the new main version when ready.
+    x-collection: directus_versions
   - name: Webhooks
     description: Webhooks.
     x-collection: directus_webhooks
@@ -259,6 +264,18 @@ paths:
   /utils/random/string:
     $ref: './paths/utils/random.yaml'
 
+  # Versions
+  /versions:
+    $ref: './paths/versions/versions.yaml'
+  /versions/{id}:
+    $ref: './paths/versions/version.yaml'
+  /versions/{id}/save:
+    $ref: './paths/versions/save.yaml'
+  /versions/{id}/compare:
+    $ref: './paths/versions/compare.yaml'
+  /versions/{id}/promote:
+    $ref: './paths/versions/promote.yaml'
+
   # Webhooks
   /webhooks:
     $ref: './paths/webhooks/webhooks.yaml'
@@ -303,6 +320,8 @@ components:
       $ref: './components/user.yaml'
     Query:
       $ref: './definitions/query.yaml'
+    Versions:
+      $ref: './components/version.yaml'
     Webhooks:
       $ref: './components/webhook.yaml'
     x-metadata:
@@ -346,6 +365,8 @@ components:
       $ref: './parameters/mode.yaml'
     Export:
       $ref: './parameters/export.yaml'
+    Version:
+      $ref: './parameters/version.yaml'
   responses:
     NotFoundError:
       $ref: './responses/notFoundError.yaml'

packages/specs/src/parameters/version.yaml

@@ -0,0 +1,7 @@
+name: version
+description: >
+  Retrieve an item's state from a specific Content Version. The value corresponds to the "key" of the Content Version.
+in: query
+required: false
+schema:
+  type: string

packages/specs/src/paths/collections/collection.yaml

@@ -70,6 +70,10 @@ patch:
                   type: string
                   example: null
                   nullable: true
+                versioning:
+                  description: Whether or not Content Versioning is enabled for this collection.
+                  type: boolean
+                  example: false
                 archive_field:
                   description: What field holds the archive value.
                   type: string

packages/specs/src/paths/collections/collections.yaml

@@ -78,6 +78,10 @@ post:
               type: string
               example: null
               nullable: true
+            versioning:
+              description: Whether or not Content Versioning is enabled for this collection.
+              type: boolean
+              example: false
             archive_field:
               description: What field holds the archive value.
               type: string

packages/specs/src/paths/items/item.yaml

@@ -7,6 +7,7 @@ get:
   parameters:
     - $ref: '../../openapi.yaml#/components/parameters/Fields'
     - $ref: '../../openapi.yaml#/components/parameters/Meta'
+    - $ref: '../../openapi.yaml#/components/parameters/Version'
   responses:
     '200':
       description: Successful request

packages/specs/src/paths/versions/compare.yaml

@@ -0,0 +1,22 @@
+get:
+  summary: Compare a Content Version
+  description: Compare an existing Content Version with the main version of the item.
+  operationId: compareContentVersion
+  parameters:
+    - $ref: '../../openapi.yaml#/components/parameters/UUId'
+  responses:
+    '200':
+      content:
+        application/json:
+          schema:
+            properties:
+              data:
+                type: object
+            type: object
+      description: Successful request
+    '401':
+      $ref: '../../openapi.yaml#/components/responses/UnauthorizedError'
+    '404':
+      $ref: '../../openapi.yaml#/components/responses/NotFoundError'
+  tags:
+    - Versions

packages/specs/src/paths/versions/promote.yaml

@@ -0,0 +1,34 @@
+post:
+  summary: Promote a Content Version
+  description:
+    Pass the current hash of the main version of the item (obtained from the `compare` endpoint) along with an optional
+    array of field names of which the values are to be promoted (by default, all fields are selected).
+  operationId: promoteContentVersion
+  parameters:
+    - $ref: '../../openapi.yaml#/components/parameters/UUId'
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            mainHash:
+              description: Hash of the main version of the item to be promoted.
+              type: string
+            fields:
+              description: Optional array of field names of which the values are to be promoted.
+              type: string
+  responses:
+    '200':
+      description: Successful request
+      content:
+        application/json:
+          schema:
+            type: object
+            properties: {}
+    '401':
+      $ref: '../../openapi.yaml#/components/responses/UnauthorizedError'
+    '404':
+      $ref: '../../openapi.yaml#/components/responses/NotFoundError'
+  tags:
+    - Versions

packages/specs/src/paths/versions/save.yaml

@@ -0,0 +1,25 @@
+post:
+  summary: Save to a Content Version
+  description: Save item changes to an existing Content Version.
+  operationId: saveContentVersion
+  parameters:
+    - $ref: '../../openapi.yaml#/components/parameters/UUId'
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+  responses:
+    '200':
+      description: Successful request
+      content:
+        application/json:
+          schema:
+            type: object
+            properties: {}
+    '401':
+      $ref: '../../openapi.yaml#/components/responses/UnauthorizedError'
+    '404':
+      $ref: '../../openapi.yaml#/components/responses/NotFoundError'
+  tags:
+    - Versions

packages/specs/src/paths/versions/version.yaml

@@ -0,0 +1,70 @@
+get:
+  summary: Retrieve a Content Version
+  description: Retrieve a single Content Version by unique identifier.
+  operationId: getContentVersion
+  parameters:
+    - $ref: '../../openapi.yaml#/components/parameters/Fields'
+    - $ref: '../../openapi.yaml#/components/parameters/Meta'
+  responses:
+    '200':
+      description: Successful request
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                $ref: '../../openapi.yaml#/components/schemas/Versions'
+    '401':
+      $ref: '../../openapi.yaml#/components/responses/UnauthorizedError'
+    '404':
+      $ref: '../../openapi.yaml#/components/responses/NotFoundError'
+  tags:
+    - Versions
+
+patch:
+  summary: Update a Content Version
+  description: Update an existing Content Version.
+  operationId: updateContentVersion
+  parameters:
+    - $ref: '../../openapi.yaml#/components/parameters/Fields'
+    - $ref: '../../openapi.yaml#/components/parameters/Meta'
+  requestBody:
+    content:
+      application/json:
+        schema:
+          anyOf:
+            - $ref: '../../openapi.yaml#/components/schemas/Versions'
+  responses:
+    '200':
+      description: Successful request
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                $ref: '../../openapi.yaml#/components/schemas/Versions'
+    '401':
+      $ref: '../../openapi.yaml#/components/responses/UnauthorizedError'
+    '404':
+      $ref: '../../openapi.yaml#/components/responses/NotFoundError'
+  tags:
+    - Versions
+
+delete:
+  summary: Delete a Content Version
+  description: Delete an existing Content Version.
+  operationId: deleteContentVersion
+  responses:
+    '200':
+      description: Successful request
+    '401':
+      $ref: '../../openapi.yaml#/components/responses/UnauthorizedError'
+    '404':
+      $ref: '../../openapi.yaml#/components/responses/NotFoundError'
+  tags:
+    - Versions
+
+parameters:
+  - $ref: '../../openapi.yaml#/components/parameters/UUId'

packages/specs/src/paths/versions/versions.yaml

@@ -0,0 +1,120 @@
+get:
+  summary: List Content Versions
+  description: Get all Content Versions.
+  operationId: getContentVersions
+  parameters:
+    - $ref: '../../openapi.yaml#/components/parameters/Fields'
+    - $ref: '../../openapi.yaml#/components/parameters/Limit'
+    - $ref: '../../openapi.yaml#/components/parameters/Offset'
+
+    - $ref: '../../openapi.yaml#/components/parameters/Meta'
+    - $ref: '../../openapi.yaml#/components/parameters/Sort'
+    - $ref: '../../openapi.yaml#/components/parameters/Filter'
+    - $ref: '../../openapi.yaml#/components/parameters/Search'
+  responses:
+    '200':
+      description: Successful request
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: array
+                items:
+                  $ref: '../../openapi.yaml#/components/schemas/Versions'
+              meta:
+                $ref: '../../openapi.yaml#/components/schemas/x-metadata'
+    '401':
+      $ref: '../../openapi.yaml#/components/responses/UnauthorizedError'
+    '404':
+      $ref: '../../openapi.yaml#/components/responses/NotFoundError'
+  tags:
+    - Versions
+
+post:
+  summary: Create Multiple Content Versions
+  description: Create multiple new Content Versions.
+  operationId: createContentVersion
+  parameters:
+    - $ref: '../../openapi.yaml#/components/parameters/Fields'
+    - $ref: '../../openapi.yaml#/components/parameters/Meta'
+  requestBody:
+    content:
+      application/json:
+        schema:
+          anyOf:
+            - $ref: '../../openapi.yaml#/components/schemas/Versions'
+  responses:
+    '200':
+      description: Successful request
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                $ref: '../../openapi.yaml#/components/schemas/Versions'
+    '401':
+      $ref: '../../openapi.yaml#/components/responses/UnauthorizedError'
+    '404':
+      $ref: '../../openapi.yaml#/components/responses/NotFoundError'
+  tags:
+    - Versions
+
+patch:
+  summary: Update Multiple Content Versions
+  description: Update multiple Content Versions at the same time.
+  operationId: updateContentVersions
+  parameters:
+    - $ref: '../../openapi.yaml#/components/parameters/Fields'
+    - $ref: '../../openapi.yaml#/components/parameters/Limit'
+    - $ref: '../../openapi.yaml#/components/parameters/Meta'
+    - $ref: '../../openapi.yaml#/components/parameters/Offset'
+
+    - $ref: '../../openapi.yaml#/components/parameters/Sort'
+    - $ref: '../../openapi.yaml#/components/parameters/Filter'
+    - $ref: '../../openapi.yaml#/components/parameters/Search'
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            data:
+              anyOf:
+                - $ref: '../../openapi.yaml#/components/schemas/Versions'
+            keys:
+              type: array
+              items:
+                type: string
+  responses:
+    '200':
+      description: Successful request
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: array
+                items:
+                  $ref: '../../openapi.yaml#/components/schemas/Versions'
+              meta:
+                $ref: '../../openapi.yaml#/components/schemas/x-metadata'
+    '401':
+      $ref: '../../openapi.yaml#/components/responses/UnauthorizedError'
+  tags:
+    - Versions
+
+delete:
+  summary: Delete Multiple Content Versions
+  description: Delete multiple existing Content Versions.
+  operationId: deleteContentVersions
+  responses:
+    '200':
+      description: Successful request
+    '401':
+      $ref: '../../openapi.yaml#/components/responses/UnauthorizedError'
+  tags:
+    - Versions