generated from corrad-software/corrad-af-2024
493 lines
9.9 KiB
Markdown
493 lines
9.9 KiB
Markdown
# EDMS API Documentation
|
|
|
|
## Overview
|
|
This document provides comprehensive API documentation for the Electronic Document Management System (EDMS). The system uses a RESTful API architecture with server-side routes in Nuxt 3.
|
|
|
|
## Authentication
|
|
All API endpoints require authentication unless specified otherwise. Authentication is handled via JWT tokens.
|
|
|
|
### Authentication Headers
|
|
```http
|
|
Authorization: Bearer <jwt_token>
|
|
Content-Type: application/json
|
|
```
|
|
|
|
## Base URL
|
|
```
|
|
Development: http://localhost:3000/api
|
|
Production: https://your-domain.com/api
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### DMS Settings API
|
|
|
|
#### GET /api/dms/settings
|
|
Retrieves current DMS configuration settings.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"statusCode": 200,
|
|
"message": "Success",
|
|
"data": {
|
|
"access": {
|
|
"userRoles": ["Admin", "Editor", "Viewer", "Uploader"],
|
|
"rbacEnabled": true,
|
|
"userGroups": ["HR Department", "Finance", "IT", "Legal"],
|
|
"permissions": {
|
|
"view": true,
|
|
"edit": true,
|
|
"delete": false,
|
|
"download": true,
|
|
"share": true
|
|
},
|
|
"authentication": {
|
|
"ssoEnabled": false,
|
|
"mfaRequired": false,
|
|
"ldapIntegration": false,
|
|
"sessionTimeout": 8
|
|
}
|
|
},
|
|
"documents": {
|
|
"folderHierarchy": {
|
|
"maxDepth": 5,
|
|
"defaultStructure": ["Department", "Project", "Category", "Year"],
|
|
"folderTemplates": ["Standard", "Project-based", "Department-based"]
|
|
},
|
|
"namingConventions": {
|
|
"autoGenerate": true,
|
|
"mandatoryFields": ["title", "department", "date"],
|
|
"pattern": "{department}_{title}_{date}"
|
|
},
|
|
"retention": {
|
|
"enabled": true,
|
|
"defaultDays": 2555,
|
|
"archiveBeforeDelete": true
|
|
},
|
|
"versionControl": {
|
|
"enabled": true,
|
|
"maxVersions": 10,
|
|
"autoVersioning": true
|
|
}
|
|
},
|
|
"metadata": {
|
|
"customFields": [
|
|
{"name": "Department", "type": "dropdown", "required": true},
|
|
{"name": "Priority", "type": "select", "required": false}
|
|
],
|
|
"tagging": {
|
|
"predefinedTags": ["urgent", "confidential", "public", "draft", "final"],
|
|
"userGeneratedTags": true,
|
|
"tagSuggestions": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### POST /api/dms/settings
|
|
Updates DMS configuration settings.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"access": {
|
|
"userRoles": ["Admin", "Editor", "Viewer"],
|
|
"rbacEnabled": true
|
|
},
|
|
"documents": {
|
|
"retention": {
|
|
"enabled": true,
|
|
"defaultDays": 365
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"statusCode": 200,
|
|
"message": "DMS settings updated successfully",
|
|
"data": {
|
|
// Updated settings object
|
|
}
|
|
}
|
|
```
|
|
|
|
### Site Settings API
|
|
|
|
#### GET /api/devtool/config/site-settings
|
|
Retrieves site configuration settings.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"statusCode": 200,
|
|
"message": "Success",
|
|
"data": {
|
|
"siteName": "EDMS Portal",
|
|
"siteDescription": "Electronic Document Management System",
|
|
"siteLogo": "/uploads/logo.png",
|
|
"themeMode": "light",
|
|
"customCSS": "",
|
|
"seoSettings": {
|
|
"title": "EDMS - Document Management",
|
|
"description": "Secure document management system",
|
|
"keywords": "document,management,security"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### POST /api/devtool/config/site-settings
|
|
Updates site configuration settings.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"siteName": "New Site Name",
|
|
"themeMode": "dark",
|
|
"customCSS": "body { background: #000; }"
|
|
}
|
|
```
|
|
|
|
### File Upload API
|
|
|
|
#### POST /api/devtool/config/upload-file
|
|
Handles file uploads for site assets.
|
|
|
|
**Request:** Multipart form data
|
|
```
|
|
file: <binary_file_data>
|
|
uploadType: "logo" | "favicon" | "background"
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"statusCode": 200,
|
|
"message": "File uploaded successfully",
|
|
"data": {
|
|
"filename": "logo_1234567890.png",
|
|
"originalName": "company-logo.png",
|
|
"size": 52480,
|
|
"mimetype": "image/png",
|
|
"path": "/uploads/logo_1234567890.png",
|
|
"url": "http://localhost:3000/uploads/logo_1234567890.png"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Authentication API
|
|
|
|
#### POST /api/auth/login
|
|
Authenticates user credentials.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"username": "user@example.com",
|
|
"password": "secure_password"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"statusCode": 200,
|
|
"message": "Authentication successful",
|
|
"data": {
|
|
"user": {
|
|
"id": "user123",
|
|
"username": "user@example.com",
|
|
"role": "admin",
|
|
"department": "IT Department"
|
|
},
|
|
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
|
}
|
|
}
|
|
```
|
|
|
|
#### GET /api/auth/logout
|
|
Logs out the current user.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"statusCode": 200,
|
|
"message": "Logout successful"
|
|
}
|
|
```
|
|
|
|
#### POST /api/auth/refresh
|
|
Refreshes authentication token.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
|
}
|
|
```
|
|
|
|
### Content Template API
|
|
|
|
#### GET /api/devtool/content/template/list
|
|
Retrieves available content templates.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"statusCode": 200,
|
|
"message": "Success",
|
|
"data": [
|
|
{
|
|
"id": "template_1",
|
|
"title": "Standard Page Template",
|
|
"description": "Basic page layout with header and content",
|
|
"category": "page",
|
|
"createdAt": "2024-01-01T00:00:00Z"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### GET /api/devtool/content/template/import
|
|
Imports a content template to a specific page.
|
|
|
|
**Query Parameters:**
|
|
- `path`: Target page path
|
|
- `templateId`: Template ID to import
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"statusCode": 200,
|
|
"message": "Template imported successfully",
|
|
"data": {
|
|
"path": "/dms/dashboard",
|
|
"templateId": "template_1",
|
|
"importedAt": "2024-01-01T00:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Error Responses
|
|
|
|
### Error Format
|
|
All API errors follow a consistent format:
|
|
|
|
```json
|
|
{
|
|
"statusCode": 400,
|
|
"message": "Error description",
|
|
"error": "BadRequest",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
### Common Error Codes
|
|
|
|
| Status Code | Error Type | Description |
|
|
|-------------|------------|-------------|
|
|
| 400 | Bad Request | Invalid request parameters |
|
|
| 401 | Unauthorized | Authentication required |
|
|
| 403 | Forbidden | Insufficient permissions |
|
|
| 404 | Not Found | Resource not found |
|
|
| 422 | Validation Error | Request validation failed |
|
|
| 429 | Rate Limited | Too many requests |
|
|
| 500 | Internal Server Error | Server error |
|
|
|
|
### Example Error Responses
|
|
|
|
#### Validation Error (422)
|
|
```json
|
|
{
|
|
"statusCode": 422,
|
|
"message": "Validation failed",
|
|
"error": "ValidationError",
|
|
"data": {
|
|
"errors": [
|
|
{
|
|
"field": "siteName",
|
|
"message": "Site name is required",
|
|
"code": "required"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Authentication Error (401)
|
|
```json
|
|
{
|
|
"statusCode": 401,
|
|
"message": "Authentication token is invalid or expired",
|
|
"error": "Unauthorized",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
## Rate Limiting
|
|
API endpoints are rate limited to prevent abuse:
|
|
|
|
- **Authentication endpoints**: 5 requests per minute per IP
|
|
- **File upload endpoints**: 10 requests per minute per user
|
|
- **General endpoints**: 100 requests per minute per user
|
|
|
|
## Request/Response Examples
|
|
|
|
### cURL Examples
|
|
|
|
#### Get DMS Settings
|
|
```bash
|
|
curl -X GET \
|
|
http://localhost:3000/api/dms/settings \
|
|
-H 'Authorization: Bearer your_jwt_token' \
|
|
-H 'Content-Type: application/json'
|
|
```
|
|
|
|
#### Update Site Settings
|
|
```bash
|
|
curl -X POST \
|
|
http://localhost:3000/api/devtool/config/site-settings \
|
|
-H 'Authorization: Bearer your_jwt_token' \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"siteName": "My EDMS Portal",
|
|
"themeMode": "dark"
|
|
}'
|
|
```
|
|
|
|
#### Upload File
|
|
```bash
|
|
curl -X POST \
|
|
http://localhost:3000/api/devtool/config/upload-file \
|
|
-H 'Authorization: Bearer your_jwt_token' \
|
|
-F 'file=@/path/to/logo.png' \
|
|
-F 'uploadType=logo'
|
|
```
|
|
|
|
### JavaScript Examples
|
|
|
|
#### Using Fetch API
|
|
```javascript
|
|
// Get DMS Settings
|
|
const response = await fetch('/api/dms/settings', {
|
|
headers: {
|
|
'Authorization': `Bearer ${token}`,
|
|
'Content-Type': 'application/json'
|
|
}
|
|
});
|
|
const data = await response.json();
|
|
|
|
// Update DMS Settings
|
|
const updateResponse = await fetch('/api/dms/settings', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Authorization': `Bearer ${token}`,
|
|
'Content-Type': 'application/json'
|
|
},
|
|
body: JSON.stringify({
|
|
access: {
|
|
rbacEnabled: true,
|
|
userRoles: ['Admin', 'User']
|
|
}
|
|
})
|
|
});
|
|
```
|
|
|
|
#### Using Nuxt useFetch
|
|
```javascript
|
|
// In Vue component
|
|
const { data, error } = await useFetch('/api/dms/settings', {
|
|
headers: {
|
|
'Authorization': `Bearer ${token}`
|
|
}
|
|
});
|
|
|
|
// Update settings
|
|
const { data: updateResult } = await useFetch('/api/dms/settings', {
|
|
method: 'POST',
|
|
body: {
|
|
access: {
|
|
rbacEnabled: true
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
## Pagination
|
|
For endpoints that return lists, pagination is implemented using:
|
|
|
|
**Query Parameters:**
|
|
- `page`: Page number (default: 1)
|
|
- `limit`: Items per page (default: 20, max: 100)
|
|
- `sort`: Sort field
|
|
- `order`: Sort order (`asc` or `desc`)
|
|
|
|
**Response Format:**
|
|
```json
|
|
{
|
|
"statusCode": 200,
|
|
"message": "Success",
|
|
"data": {
|
|
"items": [...],
|
|
"pagination": {
|
|
"currentPage": 1,
|
|
"totalPages": 5,
|
|
"totalItems": 100,
|
|
"limit": 20,
|
|
"hasNext": true,
|
|
"hasPrev": false
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## WebSocket Events
|
|
Real-time features use WebSocket connections:
|
|
|
|
### Connection
|
|
```javascript
|
|
const socket = io('/dms', {
|
|
auth: {
|
|
token: 'your_jwt_token'
|
|
}
|
|
});
|
|
```
|
|
|
|
### Events
|
|
- `document:uploaded` - New document uploaded
|
|
- `access:requested` - Access request submitted
|
|
- `access:approved` - Access request approved
|
|
- `access:rejected` - Access request rejected
|
|
- `system:maintenance` - System maintenance mode
|
|
|
|
## SDKs and Libraries
|
|
|
|
### JavaScript SDK
|
|
```javascript
|
|
import { EDMSClient } from '@edms/js-sdk';
|
|
|
|
const client = new EDMSClient({
|
|
baseURL: 'https://your-domain.com/api',
|
|
token: 'your_jwt_token'
|
|
});
|
|
|
|
// Get settings
|
|
const settings = await client.dms.getSettings();
|
|
|
|
// Update settings
|
|
await client.dms.updateSettings({
|
|
access: { rbacEnabled: true }
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
**Last Updated**: December 2024
|
|
**API Version**: v1.0
|
|
**Contact**: EDMS Development Team |