diff --git a/openapi/components/schemas/diff.yaml b/openapi/components/schemas/diff.yaml index be0bbf3..2d73f13 100644 --- a/openapi/components/schemas/diff.yaml +++ b/openapi/components/schemas/diff.yaml @@ -29,6 +29,19 @@ properties: type: array items: type: object + systemFields: + type: array + items: + type: object + properties: + collection: + type: string + field: + type: string + diff: + type: array + items: + type: object relations: type: array items: diff --git a/openapi/components/schemas/schema.yaml b/openapi/components/schemas/schema.yaml index b77960f..bf2fbae 100644 --- a/openapi/components/schemas/schema.yaml +++ b/openapi/components/schemas/schema.yaml @@ -2,6 +2,10 @@ type: object properties: version: type: integer + description: '`1` for a full snapshot, `2` for a partial snapshot.' + enum: + - 1 + - 2 example: 1 directus: type: string @@ -15,6 +19,21 @@ properties: type: array items: $ref: fields.yaml + systemFields: + type: array + description: Indexes defined on system fields. + items: + type: object + properties: + collection: + type: string + field: + type: string + schema: + type: object + properties: + is_indexed: + type: boolean relations: type: array items: diff --git a/openapi/paths/schema/apply/schemaApply.yaml b/openapi/paths/schema/apply/schemaApply.yaml index 7f16c48..b32872b 100644 --- a/openapi/paths/schema/apply/schemaApply.yaml +++ b/openapi/paths/schema/apply/schemaApply.yaml @@ -1,7 +1,8 @@ summary: Apply Schema Difference -description: Update the instance's schema by passing the diff previously retrieved - via `/schema/diff` endpoint in the JSON request body or a JSON/YAML file. This endpoint - is only available to admin users. +description: | + Update the instance's schema by passing the diff previously retrieved via `/schema/diff` endpoint in the JSON request body or a JSON/YAML file. This endpoint is only available to admin users. + + Only the operations in the diff are applied, so a diff from a partial snapshot leaves everything outside its scope untouched. The `hash` is always checked against the full schema. operationId: schemaApply parameters: - name: force diff --git a/openapi/paths/schema/diff/schemaDiff.yaml b/openapi/paths/schema/diff/schemaDiff.yaml index 8a67bec..e280552 100644 --- a/openapi/paths/schema/diff/schemaDiff.yaml +++ b/openapi/paths/schema/diff/schemaDiff.yaml @@ -5,6 +5,8 @@ description: | Alternatively, upload a JSON or YAML schema file. Does not allow different Directus versions and database vendors by default. You can opt in to bypass these checks by passing the `force` query parameter. + + Accepts partial snapshots, in which case the diff is scoped to the collections the snapshot references. operationId: schemaDiff parameters: - name: force @@ -13,6 +15,17 @@ parameters: required: false schema: type: boolean +- name: mode + description: | + `mirror` (default) returns all operations. `merge` returns an additive diff that excludes deletions. + in: query + required: false + schema: + type: string + enum: + - merge + - mirror + default: mirror requestBody: required: true content: @@ -104,6 +117,8 @@ x-codeSamples: }, ], relations: [], + }, { + mode: 'merge', }) ); diff --git a/openapi/paths/schema/snapshot/schemaSnapshot.yaml b/openapi/paths/schema/snapshot/schemaSnapshot.yaml index 8adc93e..44302c5 100644 --- a/openapi/paths/schema/snapshot/schemaSnapshot.yaml +++ b/openapi/paths/schema/snapshot/schemaSnapshot.yaml @@ -1,9 +1,36 @@ summary: Retrieve Schema Snapshot -description: Retrieve the current schema. This endpoint is only available to admin - users. +description: | + Retrieve the current schema. This endpoint is only available to admin users. + + Returns a full snapshot (version `1`) by default. Pass `includeCollections` or `excludeCollections` to scope it to a subset of collections, which returns a partial snapshot (version `2`). operationId: schemaSnapshot parameters: - $ref: ../../../components/parameters.yaml#/Export +- name: includeCollections + description: | + Restrict the snapshot to these collections. Unknown names are ignored. Mutually exclusive with `excludeCollections`. + in: query + required: false + explode: false + schema: + type: array + items: + type: string + example: + - articles + - authors +- name: excludeCollections + description: | + Snapshot every collection except these. Mutually exclusive with `includeCollections`. + in: query + required: false + explode: false + schema: + type: array + items: + type: string + example: + - articles responses: '200': description: Successful request @@ -16,6 +43,8 @@ responses: schema: type: string format: binary + '400': + $ref: ../../../components/responses.yaml#/BadRequestError '403': $ref: ../../../components/responses.yaml#/UnauthorizedError security: [] @@ -30,6 +59,11 @@ x-codeSamples: const client = createDirectus('directus_project_url').with(rest()); const result = await client.request(schemaSnapshot()); + + // Partial snapshot + const partial = await client.request( + schemaSnapshot({ includeCollections: ['articles', 'authors'] }) + ); - label: GraphQL lang: GraphQL source: |