# 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