Skip to content

Commit 63ca788

Browse files
ktuitektuite
authored
API docs for 2024.2, mainly submission deletes (#1199)
* 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
1 parent 3e190d5 commit 63ca788

File tree

1 file changed

+183
-4
lines changed

1 file changed

+183
-4
lines changed

‎docs/api.yaml

Lines changed: 183 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,12 @@ info:
4444

4545
**Added**:
4646

47-
- Extended metadata for Forms includes a new property `publicLinks`, which is the number of Public Links that can submit to the Form.
47+
* Submission Delete!
48+
- New [DELETE](/central-api-submission-management/#deleting-a-submission) and [RESTORE](/central-api-submission-management/#restoring-a-deleted-submission) endpoints for submissions!
49+
- Submissions that have been soft-deleted for 30 days will automatically be purged.
50+
* Additional properties on certain responses:
51+
- Extended metadata for Forms includes a new property `publicLinks`, which is the number of Public Links that can submit to the Form.
52+
- Data for Entity versions now includes the properties `branchId`, `trunkVersion`, and `branchBaseVersion` for supporting offline functionality.
4853

4954
## ODK Central v2024.1
5055

@@ -847,6 +852,10 @@ tags:
847852
* `submission.update` when a Submission's metadata is updated.
848853
* `submission.update.version` when a Submission XML data is updated.
849854
* `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.
855+
* `submission.delete` when a Submission is soft-deleted.
856+
* `submission.purge` when soft-deleted Submissions are purged.
857+
* `submission.restore` when a Submission is restored.
858+
* `submission.reprocess` when an Entity Submission is held in a processing backlog and then removed.
850859
* `dataset.create` when a Dataset is created.
851860
* `dataset.update` when a Dataset is updated.
852861
* `dataset.update.publish` when a Dataset is published.
@@ -857,6 +866,8 @@ tags:
857866
* `entity.delete` when an Entity is deleted.
858867
* `config.set` when a system configuration is set.
859868
* `analytics` when a Usage Report is attempted.
869+
* `blobs.s3.upload` when blobs are moved from the database to external storage.
870+
* `blobs.s3.failed-to-pending` when blobs that failed to upload are reset to the pending state to be retried.
860871
* Deprecated: `backup` when a backup operation is attempted for Google Drive backups.
861872
- name: Direct Backup
862873
x-parent-tag: System Endpoints
@@ -2971,6 +2982,8 @@ paths:
29712982
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.
29722983

29732984
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.
2985+
2986+
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.
29742987
operationId: List all Forms
29752988
parameters:
29762989
- name: projectId
@@ -2980,6 +2993,12 @@ paths:
29802993
schema:
29812994
type: number
29822995
example: "16"
2996+
- name: deleted
2997+
in: query
2998+
description: If set to `true`, will return only deleted Forms and their IDs
2999+
schema:
3000+
type: boolean
3001+
example: "true"
29833002
responses:
29843003
200:
29853004
description: OK
@@ -3299,13 +3318,18 @@ paths:
32993318
tags:
33003319
- Individual Form
33013320
summary: Deleting a Form
3302-
description: When a Form is deleted, it goes into the Trash section, but it
3321+
description: -|
3322+
When a Form is deleted, it goes into the Trash section, but it
33033323
can now be restored from the Trash. After 30 days in the Trash, the Form and
33043324
all of its resources and submissions will be automatically purged. If your
33053325
goal is to prevent it from showing up on survey clients like ODK Collect,
33063326
consider setting its `state` to `closing` or `closed` instead (see [Modifying
33073327
a Form](/central-api-form-management/#modifying-a-form) just above for
33083328
more details).
3329+
3330+
The API usually identifies forms by their `projectId` and `xmlFormId`, but if a Form
3331+
is deleted, the same `xmlFormId` can be reused. To [restore](/central-api-form-management/#restoring-a-form) a deleted Form, use its
3332+
_numeric ID_, which can be retrieved by [listing Forms with `?deleted=true`](/central-api-form-management/#list-all-forms).
33093333
operationId: Deleting a Form
33103334
parameters:
33113335
- name: xmlFormId
@@ -3811,7 +3835,9 @@ paths:
38113835
description: |-
38123836
_(introduced: version 1.4)_
38133837

3814-
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.
3838+
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.
3839+
3840+
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.
38153841
operationId: Restoring a Form
38163842
parameters:
38173843
- name: projectId
@@ -6231,6 +6257,123 @@ paths:
62316257
application/json:
62326258
schema:
62336259
$ref: '#/components/schemas/Error403'
6260+
delete:
6261+
tags:
6262+
- Submissions
6263+
summary: Deleting a Submission
6264+
description: When a Submission is deleted, there is a period of time (30 days)
6265+
during which it can be restored. After this time, all of its resources and attachments
6266+
are automatically purged. Purging deleted Submissions can also be triggered from the command line.
6267+
operationId: Deleting a Submission
6268+
parameters:
6269+
- name: projectId
6270+
in: path
6271+
description: The numeric ID of the Project
6272+
required: true
6273+
schema:
6274+
type: number
6275+
example: "16"
6276+
- name: xmlFormId
6277+
in: path
6278+
description: The `xmlFormId` of the Form being referenced.
6279+
required: true
6280+
schema:
6281+
type: string
6282+
example: simple
6283+
- name: instanceId
6284+
in: path
6285+
description: The `instanceId` of the Submission being referenced.
6286+
required: true
6287+
schema:
6288+
type: string
6289+
example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44
6290+
responses:
6291+
200:
6292+
description: OK
6293+
content:
6294+
application/json:
6295+
schema:
6296+
$ref: '#/components/schemas/Success'
6297+
403:
6298+
description: Forbidden
6299+
content:
6300+
application/json:
6301+
schema:
6302+
$ref: '#/components/schemas/Error403'
6303+
404:
6304+
description: Not Found
6305+
content:
6306+
application/json:
6307+
schema:
6308+
required:
6309+
- code
6310+
type: object
6311+
properties:
6312+
code:
6313+
type: string
6314+
message:
6315+
type: string
6316+
example:
6317+
code: "404.1"
6318+
message: Could not find the resource you were looking for.
6319+
/v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/restore:
6320+
post:
6321+
tags:
6322+
- Submissions
6323+
summary: Restoring a deleted Submission
6324+
description: Submissions that have been recently soft-deleted and not yet purged can be restored using this endpoint.
6325+
operationId: Restoring a deleted Submission
6326+
parameters:
6327+
- name: projectId
6328+
in: path
6329+
description: The numeric ID of the Project
6330+
required: true
6331+
schema:
6332+
type: number
6333+
example: "16"
6334+
- name: xmlFormId
6335+
in: path
6336+
description: The `xmlFormId` of the Form being referenced.
6337+
required: true
6338+
schema:
6339+
type: string
6340+
example: simple
6341+
- name: instanceId
6342+
in: path
6343+
description: The `instanceId` of the Submission being referenced.
6344+
required: true
6345+
schema:
6346+
type: string
6347+
example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44
6348+
responses:
6349+
200:
6350+
description: OK
6351+
content:
6352+
application/json:
6353+
schema:
6354+
$ref: '#/components/schemas/Success'
6355+
403:
6356+
description: Forbidden
6357+
content:
6358+
application/json:
6359+
schema:
6360+
$ref: '#/components/schemas/Error403'
6361+
404:
6362+
description: Not Found
6363+
content:
6364+
application/json:
6365+
schema:
6366+
required:
6367+
- code
6368+
type: object
6369+
properties:
6370+
code:
6371+
type: string
6372+
message:
6373+
type: string
6374+
example:
6375+
code: "404.1"
6376+
message: Could not find the resource you were looking for.
62346377
/v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}.xml:
62356378
get:
62366379
tags:
@@ -9014,6 +9157,9 @@ paths:
90149157
userAgent: Enketo/3.0.4
90159158
version: 1
90169159
baseVersion: null
9160+
branchId: null
9161+
trunkVersion: null
9162+
branchBaseVersion: null
90179163
conflictingProperties: null
90189164
application/json; extended:
90199165
schema:
@@ -9043,6 +9189,9 @@ paths:
90439189
userAgent: Enketo/3.0.4
90449190
version: 1
90459191
baseVersion: null
9192+
branchId: null
9193+
trunkVersion: null
9194+
branchBaseVersion: null
90469195
conflictingProperties: null
90479196
creator:
90489197
createdAt: '2018-04-18T23:19:14.802Z'
@@ -9154,6 +9303,9 @@ paths:
91549303
conflictingProperties: null
91559304
version: 1
91569305
baseVersion: null
9306+
branchId: null
9307+
trunkVersion: null
9308+
branchBaseVersion: null
91579309
data:
91589310
firstName: John
91599311
age: '88'
@@ -9235,6 +9387,9 @@ paths:
92359387
conflictingProperties: null
92369388
version: 1
92379389
baseVersion: null
9390+
branchId: null
9391+
trunkVersion: null
9392+
branchBaseVersion: null
92389393
data:
92399394
firstName: John
92409395
age: '88'
@@ -9270,6 +9425,9 @@ paths:
92709425
conflictingProperties: null
92719426
version: 1
92729427
baseVersion: null
9428+
branchId: null
9429+
trunkVersion: null
9430+
branchBaseVersion: null
92739431
data:
92749432
firstName: John
92759433
age: '88'
@@ -9432,6 +9590,9 @@ paths:
94329590
conflictingProperties: null
94339591
version: 1
94349592
baseVersion: null
9593+
branchId: null
9594+
trunkVersion: null
9595+
branchBaseVersion: null
94359596
data:
94369597
firstName: John
94379598
age: '88'
@@ -9504,6 +9665,9 @@ paths:
95049665
userAgent: Enketo/3.0.4
95059666
version: 1
95069667
baseVersion: null
9668+
branchId: null
9669+
trunkVersion: null
9670+
branchBaseVersion: null
95079671
conflict: null
95089672
resolved: false
95099673
lastGoodVersion: true
@@ -9533,6 +9697,9 @@ paths:
95339697
userAgent: Enketo/3.0.4
95349698
version: 1
95359699
baseVersion: null
9700+
branchId: null
9701+
trunkVersion: null
9702+
branchBaseVersion: null
95369703
conflict: null
95379704
resolved: false
95389705
lastGoodVersion: true
@@ -12261,7 +12428,19 @@ components:
1226112428
example: 2
1226212429
baseVersion:
1226312430
type: number
12264-
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.
12431+
description: The version number of the version that was the "base version" of this version.
12432+
example: 1
12433+
branchId:
12434+
type: string
12435+
description: The uuid of a branch linking multiple offline entity updates together.
12436+
example: b0e927b6-958a-42f6-8344-1deb37ee9672
12437+
trunkVersion:
12438+
type: number
12439+
description: The version number of the last known base server version of an entity, in the case of an offline branch of updates.
12440+
example: 1
12441+
branchBaseVersion:
12442+
type: number
12443+
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.
1226512444
example: 1
1226612445
EntitySummary:
1226712446
allOf:

0 commit comments

Comments
 (0)