diff --git a/openapi/index.yaml b/openapi/index.yaml index 51893a3..ab0e51d 100644 --- a/openapi/index.yaml +++ b/openapi/index.yaml @@ -261,6 +261,8 @@ paths: $ref: paths/utils/hash/generate/index.yaml "/utils/hash/verify": $ref: paths/utils/hash/verify/index.yaml + "/utils/import": + $ref: paths/utils/import/index.yaml "/utils/import/{collection}": $ref: paths/utils/import/_collection/index.yaml "/utils/random/string": diff --git a/openapi/paths/utils/import/importBatch.yaml b/openapi/paths/utils/import/importBatch.yaml new file mode 100644 index 0000000..22356fb --- /dev/null +++ b/openapi/paths/utils/import/importBatch.yaml @@ -0,0 +1,132 @@ +summary: Import Multiple Collections +description: >- + Import flat data for multiple related collections in a single request. Relations are resolved from the schema so + collections are imported in dependency order and primary keys (and the foreign keys referencing them) are remapped. + The payload is uploaded as a JSON file (`multipart/form-data`) containing an array of `{ collection, items }` + objects, for example: + + + ```json + + [ + { "collection": "authors", "items": [{ "id": "123", "name": "Lorem Ipsum" }] }, + { "collection": "articles", "items": [{ "id": "123", "title": "Hello World", "author": "123" }] } + ] + + ``` +operationId: importBatch +parameters: +- description: >- + `add` inserts new items and remaps conflicting primary keys, `merge` upserts items. Defaults to `add`. + in: query + name: mode + required: false + schema: + type: string + enum: + - add + - merge +- description: When true, no data is persisted; the computed id mappings are still returned. + in: query + name: dryRun + required: false + schema: + type: boolean +- description: >- + Only valid with `mode=merge`. Deletes any existing records in the imported collections whose primary key is + absent from the import, mirroring the payload. Destructive. + in: query + name: dangerouslyAllowDelete + required: false + schema: + type: boolean +requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + file: + type: string + format: binary + description: >- + A JSON file containing an array of `{ collection, items }` objects. +responses: + '200': + description: Successful request + content: + application/json: + schema: + type: object + properties: + data: + type: object + properties: + applied: + type: boolean + description: Whether the changes were committed. `false` for a dry run. + mode: + type: string + enum: + - add + - merge + collections: + type: object + description: Per-collection summary of the changes made. + additionalProperties: + type: object + properties: + existing: + type: array + description: Primary keys of pre-existing records that were matched and updated. + items: + type: string + new: + type: array + description: Primary keys of newly created records. + items: + type: string + deleted: + type: array + description: Primary keys of records that were deleted (only when `dangerouslyAllowDelete` is set). + items: + type: string + mapped: + type: object + description: Provided primary key -> new primary key, for records whose key was remapped. + '403': + $ref: ../../../components/responses.yaml#/ForbiddenError + '415': + description: "Error: Unsupported media type." + content: + application/json: + schema: + type: object + properties: + error: + type: object + properties: + code: + type: integer + format: int64 + message: + type: string +security: [] +tags: +- Utilities +x-codeSamples: + - label: Directus SDK + lang: JavaScript + source: | + import { createDirectus, rest, utilsImportBatch } from '@directus/sdk'; + + const client = createDirectus('directus_project_url').with(rest()); + + const formData = new FormData(); + formData.append('file', raw_file); + + const result = await client.request(utilsImportBatch(formData, { mode: 'add' })); + - label: GraphQL + lang: GraphQL + source: | + // Not currently available in GraphQL diff --git a/openapi/paths/utils/import/index.yaml b/openapi/paths/utils/import/index.yaml new file mode 100644 index 0000000..c0bb1bb --- /dev/null +++ b/openapi/paths/utils/import/index.yaml @@ -0,0 +1,2 @@ +post: + $ref: importBatch.yaml