Merged in feature/add-deletes (pull request #214)
support delete for client, document and folder * support delete for client, document and folder * remove batch cancel conflict not used Approved-by: Jacob Mathison
This commit is contained in:
Jay Brown
@@ -266,6 +266,36 @@ Updates client information.
|
||||
|
||||
**Response**: `200` Client updated successfully
|
||||
|
||||
### `DELETE /client/{id}`
|
||||
|
||||
Permanently deletes a client and all associated data: documents (with all dependent rows), folders, collector configurations, batch uploads, and clientCanSync records. Source documents in S3 are NOT deleted; their paths are logged and optionally returned. This operation is irreversible.
|
||||
|
||||
**Security**: Requires JWT authentication. Restricted to `super_admin` role only.
|
||||
|
||||
**Query Parameters**:
|
||||
|
||||
- `confirm` (required, boolean): Must be `true` to proceed. Returns `400 Bad Request` if absent or false.
|
||||
- `verbose` (optional, boolean, default: false): When `true`, returns S3 paths of orphaned source documents.
|
||||
|
||||
**Response**:
|
||||
|
||||
- `204`: Client deleted successfully (when `verbose=false`)
|
||||
- `200`: Client deleted successfully with S3 paths (when `verbose=true`):
|
||||
|
||||
```json
|
||||
{
|
||||
"deletedDocuments": [
|
||||
{
|
||||
"documentId": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
|
||||
"s3Path": "s3://bucket-name/key/path/to/file"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- `400`: Missing `confirm=true` query parameter
|
||||
- `404`: Client not found
|
||||
|
||||
### `GET /client/{id}/status`
|
||||
|
||||
Returns client synchronization status.
|
||||
@@ -356,6 +386,38 @@ Retrieves enriched document details by ID, including metadata such as folder, fi
|
||||
}
|
||||
```
|
||||
|
||||
### `DELETE /document/{id}`
|
||||
|
||||
Permanently deletes a document and all dependent data: document entries, cleans (and their entries), text extractions (and their entries), field extractions (versions and array fields), labels, results, and result dependencies. Source documents in S3 are NOT deleted; their paths are logged and optionally returned.
|
||||
|
||||
**Security**: Requires JWT authentication. Restricted to `super_admin` role only.
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
- `id`: Document UUID (max 36 chars)
|
||||
|
||||
**Query Parameters**:
|
||||
|
||||
- `verbose` (optional, boolean, default: false): When `true`, returns S3 paths of orphaned source documents.
|
||||
|
||||
**Response**:
|
||||
|
||||
- `204`: Document deleted successfully (when `verbose=false`)
|
||||
- `200`: Document deleted successfully with S3 paths (when `verbose=true`):
|
||||
|
||||
```json
|
||||
{
|
||||
"deletedDocuments": [
|
||||
{
|
||||
"documentId": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
|
||||
"s3Path": "s3://bucket-name/key/path/to/file"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- `404`: Document not found
|
||||
|
||||
---
|
||||
|
||||
## Batch Document Operations (DocumentsService)
|
||||
@@ -448,17 +510,6 @@ Retrieves detailed status information for a specific batch upload.
|
||||
}
|
||||
```
|
||||
|
||||
### `DELETE /client/{id}/document/batch/{batch_id}`
|
||||
|
||||
Cancels a batch upload that is currently processing.
|
||||
|
||||
**Security**: Requires JWT authentication
|
||||
|
||||
**Response**:
|
||||
|
||||
- `204`: Batch upload cancelled successfully
|
||||
- `404`: Batch not found
|
||||
|
||||
---
|
||||
|
||||
## Folder Operations (FolderService)
|
||||
@@ -612,6 +663,40 @@ Renames an existing folder.
|
||||
|
||||
**Response** (`200 OK`): Updated folder object
|
||||
|
||||
### `DELETE /folders/{folderId}`
|
||||
|
||||
Permanently deletes a folder and all child folders recursively. The root folder (`/`) cannot be deleted. If the folder tree contains documents, the caller must either delete the documents first or pass `include_documents=true`.
|
||||
|
||||
**Security**: Requires JWT authentication. Restricted to `super_admin` role only.
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
- `folderId`: Folder UUID
|
||||
|
||||
**Query Parameters**:
|
||||
|
||||
- `include_documents` (optional, boolean, default: false): When `true`, deletes all documents in the folder tree along with the folders. When `false` and the folder tree contains documents, returns `409 Conflict`.
|
||||
- `verbose` (optional, boolean, default: false): When `true`, returns S3 paths of orphaned source documents.
|
||||
|
||||
**Response**:
|
||||
|
||||
- `204`: Folder tree deleted successfully (when `verbose=false`)
|
||||
- `200`: Folder tree deleted successfully with S3 paths (when `verbose=true`):
|
||||
|
||||
```json
|
||||
{
|
||||
"deletedDocuments": [
|
||||
{
|
||||
"documentId": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
|
||||
"s3Path": "s3://bucket-name/key/path/to/file"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- `404`: Folder not found
|
||||
- `409`: Cannot delete root folder, or folder tree contains documents and `include_documents` is not `true`
|
||||
|
||||
### `GET /folders/{folderId}/documents`
|
||||
|
||||
Retrieves all documents within a specific folder, including filename and labels. Returns a lighter-weight format than `GET /document/{id}` (excludes `client_id`).
|
||||
@@ -1637,20 +1722,22 @@ The following table shows what data is passed to Permit.io for each protected en
|
||||
| `GET` | `/clients` | `clients` | `get` | List all clients |
|
||||
| `GET` | `/client/{id}` | `client` | `get` | Get client details |
|
||||
| `PATCH` | `/client/{id}` | `client` | `patch` | Update client |
|
||||
| `DELETE` | `/client/{id}` | `client` | `delete` | Hard-delete client (super_admin only) |
|
||||
| `GET` | `/client/{id}/status` | `client` | `get` | Get client sync status |
|
||||
| **Document Operations** |
|
||||
| `POST` | `/client/{id}/document` | `client` | `post` | Upload document |
|
||||
| `GET` | `/client/{id}/document` | `client` | `get` | List client documents |
|
||||
| `GET` | `/document/{id}` | `document` | `get` | Get document details |
|
||||
| `DELETE` | `/document/{id}` | `document` | `delete` | Hard-delete document (super_admin only) |
|
||||
| **Batch Document Operations** |
|
||||
| `POST` | `/client/{id}/document/batch` | `client` | `post` | Upload batch (ZIP) |
|
||||
| `GET` | `/client/{id}/document/batch` | `client` | `get` | List batch uploads |
|
||||
| `GET` | `/client/{id}/document/batch/{batch_id}` | `client` | `get` | Get batch status |
|
||||
| `DELETE` | `/client/{id}/document/batch/{batch_id}` | `client` | `delete` | Cancel batch upload |
|
||||
| **Folder Operations** |
|
||||
| `GET` | `/client/{id}/folders` | `client` | `get` | List client folders |
|
||||
| `POST` | `/folders` | `folders` | `post` | Create folder |
|
||||
| `PATCH` | `/folders/{folderId}` | `folders` | `patch` | Rename folder |
|
||||
| `DELETE` | `/folders/{folderId}` | `folders` | `delete` | Hard-delete folder tree (super_admin only) |
|
||||
| `GET` | `/folders/{folderId}/documents` | `folders` | `get` | List folder documents |
|
||||
| `GET` | `/folders/{folderId}/metrics` | `folders` | `get` | Get folder metrics |
|
||||
| **Label Operations** |
|
||||
@@ -1717,16 +1804,18 @@ To configure Permit.io to work with this API, administrators must create:
|
||||
| `delete` | DELETE | Delete resources |
|
||||
| `head` | HEAD | Check resource existence |
|
||||
|
||||
#### Example Role Configuration
|
||||
#### Role Configuration
|
||||
|
||||
Typical role assignments for common personas:
|
||||
The following roles are defined in the Permit.io configuration (`cmd/auth_related/permit.setup/permit_policies.yaml`):
|
||||
|
||||
| Role | Resources | Actions | Use Case |
|
||||
| ------------ | -------------------------------------------------------------------------- | ---------------------- | -------------------------- |
|
||||
| `viewer` | `client`, `clients`, `document`, `documents`, `folders`, `export` | `get` | Read-only access |
|
||||
| `editor` | `client`, `document`, `documents`, `folders`, `field-extractions` | `get`, `post`, `patch` | Content management |
|
||||
| `admin` | All resources | All actions | Full administrative access |
|
||||
| `user_admin` | `admin` | All actions | User management only |
|
||||
| Role | Resources | Actions | Use Case |
|
||||
| -------------- | -------------------------------------------------------------------------------------- | -------------------------------- | --------------------------------------- |
|
||||
| `super_admin` | All resources | All actions including `delete` | Full administrative access |
|
||||
| `user_admin` | `admin`, `documents`, `field-extractions`, `folders` | `get`, `post`, `patch`, `delete` (admin only) | User management |
|
||||
| `auditor` | `admin`, `client`, `clients`, `document`, `export`, `documents`, `field-extractions`, `folders`, `labels` | `get` (and `head` for admin) | Read-only access for auditing |
|
||||
| `client_user` | `client`, `clients`, `document`, `export`, `documents`, `field-extractions`, `folders`, `labels` | `get`, `post`, `patch` (varies by resource) | Client-specific access |
|
||||
|
||||
**Delete permissions**: Only `super_admin` has `delete` access to `client`, `document`, and `folders` resources. The `client_user` role does NOT have `client:delete` or any other delete permissions on these resources.
|
||||
|
||||
### Authorization Error Responses
|
||||
|
||||
|
||||
Reference in New Issue
Block a user