Update API doc

sadiqkhoja · Jan 3, 2025 · 813fc25 · 813fc25
1 parent 0f5d716
commit 813fc25
Showing 1 changed file with 106 additions and 47 deletions.
diff --git a/docs/api.yaml b/docs/api.yaml
@@ -40,14 +40,21 @@ info:
 
     Here major and breaking changes to the API are listed by version.
 
+    ## ODK Central v2025.1
+
+    **Added**:
+    - [RESTORE](/central-api-entity-management/#restoring-a-deleted-entity) endpoint for Entities.
+    - Entities that have been soft-deleted for 30 days will automatically be purged. 
+    - [Entities Odata](/central-api-odata-endpoints/#id3) now returns `__system/deletedAt`. It can also be used in $filter, $sort and $select query parameters.
+
     ## ODK Central v2024.3
 
     **Added**:
     - Endpoints for managing [User Preferences](/central-api-accounts-and-users/#user-preferences), mainly to be used by the frontend.
 
     **Changed**:
 
-    - [Submissions Odata]() now returns `__system/deletedAt`. It can also be used in $filter, $sort and $select query parameters.
+    - [Submissions Odata](/central-api-odata-endpoints/#data-document) now returns `__system/deletedAt`. It can also be used in $filter, $sort and $select query parameters.
     - Dataset (Entity List) properties with the same name but different capitalization are not allowed.
     - Form Attachments for both [published Forms](/central-api-form-management/#listing-form-attachments) and [draft Forms](/central-api-form-management/#listing-expected-draft-form-attachments) now return a property representing the hash of the attachment file.
 
@@ -9155,51 +9162,6 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error403'
-    delete:
-      tags:
-      - Entity Management
-      summary: Deleting an Entity
-      description: Use this API to delete an Entity. With this API, Entity is soft-deleted,
-        which means it is still in the database and you can retreive it by passing
-        `?deleted=true` to [GET /projects/:id/datasets/:name/entities](/central-api-entity-management/#entities-metadata).
-        In the future, we will provide a way to restore deleted entities and purge
-        deleted entities.
-      operationId: Deleting an Entity
-      parameters:
-      - name: projectId
-        in: path
-        description: The numeric ID of the Project
-        required: true
-        schema:
-          type: number
-        example: "16"
-      - name: name
-        in: path
-        description: Name of the Dataset
-        required: true
-        schema:
-          type: string
-        example: people
-      - name: uuid
-        in: path
-        description: UUID of the Entity
-        required: true
-        schema:
-          type: string
-        example: 54a405a0-53ce-4748-9788-d23a30cc3afa
-      responses:
-        200:
-          description: OK
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Success'
-        403:
-          description: Forbidden
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error403'
     patch:
       tags:
       - Entity Management
@@ -9314,6 +9276,100 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error403'
       x-codegen-request-body-name: body
+    delete:
+      tags:
+      - Entity Management
+      summary: Deleting an Entity
+      description: Use this API to delete an Entity. With this API, Entity is soft-deleted,
+        which means it is still in the database and you can retreive it by passing
+        `?deleted=true` to [GET /projects/:id/datasets/:name/entities](/central-api-entity-management/#entities-metadata).
+        In the future, we will provide a way to restore deleted entities and purge
+        deleted entities.
+      operationId: Deleting an Entity
+      parameters:
+      - name: projectId
+        in: path
+        description: The numeric ID of the Project
+        required: true
+        schema:
+          type: number
+        example: "16"
+      - name: name
+        in: path
+        description: Name of the Dataset
+        required: true
+        schema:
+          type: string
+        example: people
+      - name: uuid
+        in: path
+        description: UUID of the Entity
+        required: true
+        schema:
+          type: string
+        example: 54a405a0-53ce-4748-9788-d23a30cc3afa
+      responses:
+        200:
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Success'
+        403:
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error403'
+
+  /projects/{projectId}/datasets/{name}/entities/{uuid}/restore:
+    post:
+      tags:
+      - Entity Management
+      summary: Restoring a deleted Entity
+      description: Entities that have been recently soft-deleted and not yet purged can be restored using this endpoint.
+      operationId: Restoring a deleted Entity
+      parameters:
+      - name: projectId
+        in: path
+        description: The numeric ID of the Project
+        required: true
+        schema:
+          type: number
+        example: "16"
+      - name: name
+        in: path
+        description: Name of the Dataset
+        required: true
+        schema:
+          type: string
+        example: people
+      - name: uuid
+        in: path
+        description: UUID of the Entity
+        required: true
+        schema:
+          type: string
+        example: 54a405a0-53ce-4748-9788-d23a30cc3afa
+      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:
+                $ref: '#/components/schemas/Error404'
   /projects/{projectId}/datasets/{name}/entities/{uuid}/versions:
     get:
       tags:
@@ -10912,8 +10968,9 @@ paths:
         | Entity Timestamp        | `__system/createdAt` |
         | Entity Update Timestamp | `__system/updatedAt` |
         | Entity Conflict         | `__system/conflict`  |
+        | Entity Delete Timestamp | `__system/deletedAt` |
 
-        Note that `createdAt` and `updatedAt` are time components. This means that any comparisons you make need to account for the full time of the entity. It might seem like `$filter=__system/createdAt le 2020-01-31` would return all results on or before 31 Jan 2020, but in fact only entities made before midnight of that day would be accepted. To include all of the month of January, you need to filter by either `$filter=__system/createdAt le 2020-01-31T23:59:59.999Z` or `$filter=__system/createdAt lt 2020-02-01`. Remember also that you can [query by a specific timezone](https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC).
+        Note that `createdAt`, `updatedAt` and `deletedAt` are time components. This means that any comparisons you make need to account for the full time of the entity. It might seem like `$filter=__system/createdAt le 2020-01-31` would return all results on or before 31 Jan 2020, but in fact only entities made before midnight of that day would be accepted. To include all of the month of January, you need to filter by either `$filter=__system/createdAt le 2020-01-31T23:59:59.999Z` or `$filter=__system/createdAt lt 2020-02-01`. Remember also that you can [query by a specific timezone](https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC).
 
         Please see the [OData documentation](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358948) on `$filter` [operations](http://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_BuiltinFilterOperations) and [functions](http://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_BuiltinQueryFunctions) for more information.
 
@@ -11007,6 +11064,7 @@ paths:
                     creatorName: Tree surveyor
                     updates: 1,
                     updatedAt: '2023-04-31T19:41:16.478Z'
+                    deletedAt: null
                     version: 1
                     conflict: null
                 - __id: aeebd746-3b1e-4a24-ba9d-ed6547bd5ff1
@@ -11017,6 +11075,7 @@ paths:
                     creatorName: Tree surveyor
                     updates: 1,
                     updatedAt: '2023-04-31T19:41:16.478Z'
+                    deletedAt: null
                     version: 2
                     conflict: null
                   geometry: 47.722581 18.562111 0 0,