EDMS/dms-api.md

# DMS API Documentation

## Folders

### GET /api/dms/folder
- **Description**: Retrieves all folders/cabinets in the DMS
- **Method**: GET
- **Response**: List of all folders with their details
- **Response Example**:
  ```json
  {
    "status": 200,
    "message": "Backend data sent successfully",
    "folders": [...]
  }
  ```

### POST /api/dms/folder
- **Description**: Creates a new folder/cabinet in the DMS
- **Method**: POST
- **Request Body**:
  ```json
  {
    "cabinet_name": "Cabinet 1",
    "cabinet_parent_id": null,
    "cabinet_owner": "",
    "cabinet_sector": "",
    "dp_id": null,
    "userID": null
  }
  ```
- **Required Fields**: cabinet_name, cabinet_sector
- **Validation**:
  - Parent folder must exist (cabinet_parent_id must be valid)
- **Response Example**:
  ```json
  {
    "status": 201,
    "message": "Folder created successfully",
    "folder": {...}
  }
  ```
- **Error Responses**:
  ```json
  {
    "status": 400,
    "message": "cabinet_name and cabinet_sector are required"
  }
  ```
  ```json
  {
    "status": 400,
    "message": "Parent folder does not exist"
  }
  ```
  ```json
  {
    "status": 400,
    "message": "Body was not received"
  }
  ```

### PATCH /api/dms/folder
- **Description**: Updates an existing folder (rename or move)
- **Method**: PATCH
- **Request Body**:
  ```json
  {
    "function": "rename|move",
    "cabinet_id": "folder-id",
    "new_name": "New Folder Name",
    "new_parent_id": "parent-folder-id"
  }
  ```
- **Required Fields**: cabinet_id, function
- **Functions**:
  - `rename`: Changes folder name (requires new_name)
  - `move`: Changes parent folder (requires new_parent_id)
- **Response Example**:
  ```json
  {
    "status": 200,
    "message": "Folder renamed successfully",
    "folder": {...}
  }
  ```

### DELETE /api/dms/folder
- **Description**: Deletes an existing folder/cabinet from the DMS
- **Method**: DELETE
- **Request Body**:
  ```json
  {
    "cabinet_id": "folder-id"
  }
  ```
- **Required Fields**: cabinet_id
- **Response Example**:
  ```json
  {
    "status": 200,
    "message": "Folder deleted successfully",
    "folder": {...}
  }
  ```

## Settings

### GET /api/dms/settings
- **Description**: Retrieves DMS configuration settings
- **Method**: GET
- **Response**: Comprehensive settings for the DMS organized by category
- **Categories**:
  - User & Access Management
  - Document & Folder Settings
  - Metadata & Tagging
  - Workflow & Automation
  - Upload & Storage Settings
  - System Settings

### POST /api/dms/settings
- **Description**: Updates DMS configuration settings
- **Method**: POST
- **Request Body**: Object containing settings to update, structured by category
- **Categories**:
  - access: User roles, permissions, authentication
  - documents: Folder hierarchy, naming conventions, retention, version control
  - metadata: Custom fields, tagging, classification
  - workflow: Approval flows, notifications, automation
  - upload: File types, size limits, quotas, storage
  - system: Timezone, backup, maintenance, monitoring
- **Response Example**:
  ```json
  {
    "statusCode": 200,
    "message": "DMS settings updated successfully",
    "data": { "settingID": 1 }
  }
  ```

## Files

### POST /api/dms/upload-file
- **Description**: Generates a signed URL for direct file upload to S3
- **Method**: POST
- **Content-Type**: multipart/form-data
- **Request Body**:
  ```json
  {
    "fileName": "example.pdf",
    "fileType": "application/pdf"
  }
  ```
- **Required Fields**: fileName, fileType
- **Response Example**:
  ```json
  {
    "status": 200,
    "message": "Signed URL generated for file: example.pdf",
    "signedUrl": "https://bucket-name.s3.region.amazonaws.com/..."
  }
  ```
- **Error Responses**:
  ```json
  {
    "status": 400,
    "message": "Missing required fields { fileName, fileType }"
  }
  ```
  ```json
  {
    "status": 500,
    "message": "Failed to generate signed URL",
    "error": "Error details..."
  }
  ```
- **Notes**: 
  - The signed URL expires after 60 seconds
  - Use the returned signedUrl with a PUT request to upload the file directly to S3
  - Include the file's Content-Type header when uploading to S3