Skip to content

Commit

Permalink
API docs for 2024.2, mainly submission deletes (#1199)
Browse files Browse the repository at this point in the history 
* Extra entity fields for offline management

* submission deletes

* notes about restoring deleted forms by id

* link changelog to parts of docs

* Add additional server audit log events to list
  • Loading branch information
@ktuite
ktuite authored Sep 26, 2024
1 parent 3e190d5 commit 63ca788
Showing 1 changed file with 183 additions and 4 deletions.
187 changes: 183 additions & 4 deletions docs/api.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -9154,6 +9303,9 @@ paths:
conflictingProperties: null
version: 1
baseVersion: null
branchId: null
trunkVersion: null
branchBaseVersion: null
data:
firstName: John
age: '88'
Expand Down Expand Up @@ -9235,6 +9387,9 @@ paths:
conflictingProperties: null
version: 1
baseVersion: null
branchId: null
trunkVersion: null
branchBaseVersion: null
data:
firstName: John
age: '88'
Expand Down Expand Up @@ -9270,6 +9425,9 @@ paths:
conflictingProperties: null
version: 1
baseVersion: null
branchId: null
trunkVersion: null
branchBaseVersion: null
data:
firstName: John
age: '88'
Expand Down Expand Up @@ -9432,6 +9590,9 @@ paths:
conflictingProperties: null
version: 1
baseVersion: null
branchId: null
trunkVersion: null
branchBaseVersion: null
data:
firstName: John
age: '88'
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down

0 comments on commit 63ca788

Please sign in to comment.