diff --git a/docs/api.yaml b/docs/api.yaml index 16864ab99..aa3ef4693 100644 --- a/docs/api.yaml +++ b/docs/api.yaml @@ -44,7 +44,12 @@ info: **Added**: - - Extended metadata for Forms includes a new property `publicLinks`, which is the number of Public Links that can submit to the Form. + * Submission Delete! + - New [DELETE](/central-api-submission-management/#deleting-a-submission) and [RESTORE](/central-api-submission-management/#restoring-a-deleted-submission) endpoints for submissions! + - Submissions that have been soft-deleted for 30 days will automatically be purged. + * Additional properties on certain responses: + - Extended metadata for Forms includes a new property `publicLinks`, which is the number of Public Links that can submit to the Form. + - Data for Entity versions now includes the properties `branchId`, `trunkVersion`, and `branchBaseVersion` for supporting offline functionality. ## ODK Central v2024.1 @@ -847,6 +852,10 @@ tags: * `submission.update` when a Submission's metadata is updated. * `submission.update.version` when a Submission XML data is updated. * `submission.attachment.update` when a Submission Attachment binary is set or cleared, but _only via the REST API_. Attachments created alongside the submission over the OpenRosa `/submission` API (including submissions from Collect) do not generate audit log entries. + * `submission.delete` when a Submission is soft-deleted. + * `submission.purge` when soft-deleted Submissions are purged. + * `submission.restore` when a Submission is restored. + * `submission.reprocess` when an Entity Submission is held in a processing backlog and then removed. * `dataset.create` when a Dataset is created. * `dataset.update` when a Dataset is updated. * `dataset.update.publish` when a Dataset is published. @@ -857,6 +866,8 @@ tags: * `entity.delete` when an Entity is deleted. * `config.set` when a system configuration is set. * `analytics` when a Usage Report is attempted. + * `blobs.s3.upload` when blobs are moved from the database to external storage. + * `blobs.s3.failed-to-pending` when blobs that failed to upload are reset to the pending state to be retried. * Deprecated: `backup` when a backup operation is attempted for Google Drive backups. - name: Direct Backup x-parent-tag: System Endpoints @@ -2971,6 +2982,8 @@ paths: As of version 1.2, Forms that are unpublished (that only carry a draft and have never been published) will appear with full metadata detail. Previously, certain details like `name` were omitted. You can determine that a Form is unpublished by checking the `publishedAt` value: it will be `null` for unpublished forms. This endpoint supports retrieving extended metadata; provide a header `X-Extended-Metadata: true` to additionally retrieve the `submissions` count of the number of Submissions that each Form has, the `reviewStates` object of counts of Submissions with specific review states, the `lastSubmission` most recent submission timestamp, the Actor the Form was `createdBy`, as well as other metadata. + + The query `?deleted=true` can be added to list deleted Forms with their numeric form IDs, which can be used to [restore](/central-api-form-management/#restoring-a-form) a deleted Form. operationId: List all Forms parameters: - name: projectId @@ -2980,6 +2993,12 @@ paths: schema: type: number example: "16" + - name: deleted + in: query + description: If set to `true`, will return only deleted Forms and their IDs + schema: + type: boolean + example: "true" responses: 200: description: OK @@ -3299,13 +3318,18 @@ paths: tags: - Individual Form summary: Deleting a Form - description: When a Form is deleted, it goes into the Trash section, but it + description: -| + When a Form is deleted, it goes into the Trash section, but it can now be restored from the Trash. After 30 days in the Trash, the Form and all of its resources and submissions will be automatically purged. If your goal is to prevent it from showing up on survey clients like ODK Collect, consider setting its `state` to `closing` or `closed` instead (see [Modifying a Form](/central-api-form-management/#modifying-a-form) just above for more details). + + The API usually identifies forms by their `projectId` and `xmlFormId`, but if a Form + is deleted, the same `xmlFormId` can be reused. To [restore](/central-api-form-management/#restoring-a-form) a deleted Form, use its + _numeric ID_, which can be retrieved by [listing Forms with `?deleted=true`](/central-api-form-management/#list-all-forms). operationId: Deleting a Form parameters: - name: xmlFormId @@ -3811,7 +3835,9 @@ paths: description: |- _(introduced: version 1.4)_ - Deleted forms can now be restored (as long as they have been in the Trash less than 30 days and have not been purged). However, a deleted Form with the same `xmlFormId` as an active Form cannot be restored while that other Form is active. This `/restore` URL uses the numeric ID of the Form (now returned by the `/forms` endpoint) rather than the `xmlFormId` to unambigously restore. + Deleted forms can now be restored (as long as they have been in the Trash less than 30 days and have not been purged). However, a deleted Form with the same `xmlFormId` as an active Form cannot be restored while that other Form is active. + + This `/restore` URL uses the numeric ID of the Form (now returned by the `/forms?deleted=true` endpoint) rather than the `xmlFormId` to unambigously restore. Note that the numeric ID of a Form is not returned by default on the [Form list](/central-api-form-management/#list-all-forms) and is only returned when listing deleted Forms. operationId: Restoring a Form parameters: - name: projectId @@ -6231,6 +6257,123 @@ paths: application/json: schema: $ref: '#/components/schemas/Error403' + delete: + tags: + - Submissions + summary: Deleting a Submission + description: When a Submission is deleted, there is a period of time (30 days) + during which it can be restored. After this time, all of its resources and attachments + are automatically purged. Purging deleted Submissions can also be triggered from the command line. + operationId: Deleting a Submission + parameters: + - name: projectId + in: path + description: The numeric ID of the Project + required: true + schema: + type: number + example: "16" + - name: xmlFormId + in: path + description: The `xmlFormId` of the Form being referenced. + required: true + schema: + type: string + example: simple + - name: instanceId + in: path + description: The `instanceId` of the Submission being referenced. + required: true + schema: + type: string + example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Success' + 403: + description: Forbidden + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + 404: + description: Not Found + content: + application/json: + schema: + required: + - code + type: object + properties: + code: + type: string + message: + type: string + example: + code: "404.1" + message: Could not find the resource you were looking for. + /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/restore: + post: + tags: + - Submissions + summary: Restoring a deleted Submission + description: Submissions that have been recently soft-deleted and not yet purged can be restored using this endpoint. + operationId: Restoring a deleted Submission + parameters: + - name: projectId + in: path + description: The numeric ID of the Project + required: true + schema: + type: number + example: "16" + - name: xmlFormId + in: path + description: The `xmlFormId` of the Form being referenced. + required: true + schema: + type: string + example: simple + - name: instanceId + in: path + description: The `instanceId` of the Submission being referenced. + required: true + schema: + type: string + example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Success' + 403: + description: Forbidden + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + 404: + description: Not Found + content: + application/json: + schema: + required: + - code + type: object + properties: + code: + type: string + message: + type: string + example: + code: "404.1" + message: Could not find the resource you were looking for. /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}.xml: get: tags: @@ -9014,6 +9157,9 @@ paths: userAgent: Enketo/3.0.4 version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null conflictingProperties: null application/json; extended: schema: @@ -9043,6 +9189,9 @@ paths: userAgent: Enketo/3.0.4 version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null conflictingProperties: null creator: createdAt: '2018-04-18T23:19:14.802Z' @@ -9154,6 +9303,9 @@ paths: conflictingProperties: null version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null data: firstName: John age: '88' @@ -9235,6 +9387,9 @@ paths: conflictingProperties: null version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null data: firstName: John age: '88' @@ -9270,6 +9425,9 @@ paths: conflictingProperties: null version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null data: firstName: John age: '88' @@ -9432,6 +9590,9 @@ paths: conflictingProperties: null version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null data: firstName: John age: '88' @@ -9504,6 +9665,9 @@ paths: userAgent: Enketo/3.0.4 version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null conflict: null resolved: false lastGoodVersion: true @@ -9533,6 +9697,9 @@ paths: userAgent: Enketo/3.0.4 version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null conflict: null resolved: false lastGoodVersion: true @@ -12261,7 +12428,19 @@ components: example: 2 baseVersion: type: number - description: The version number of the version that was the "base version" of this version. The base version is the version that was shown to the data collector when they made their update. + description: The version number of the version that was the "base version" of this version. + example: 1 + branchId: + type: string + description: The uuid of a branch linking multiple offline entity updates together. + example: b0e927b6-958a-42f6-8344-1deb37ee9672 + trunkVersion: + type: number + description: The version number of the last known base server version of an entity, in the case of an offline branch of updates. + example: 1 + branchBaseVersion: + type: number + description: The base version of the entity according to the submission. In the case of an offline branch of updates, this may not match the version of the base submission on Central. example: 1 EntitySummary: allOf: