EDMS/docs/API_DOCUMENTATION.md

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

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:

{
  "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:

{
  "access": {
    "userRoles": ["Admin", "Editor", "Viewer"],
    "rbacEnabled": true
  },
  "documents": {
    "retention": {
      "enabled": true,
      "defaultDays": 365
    }
  }
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "username": "user@example.com",
  "password": "secure_password"
}

Response:

{
  "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:

{
  "statusCode": 200,
  "message": "Logout successful"
}

POST /api/auth/refresh

Refreshes authentication token.

Request Body:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Content Template API

GET /api/devtool/content/template/list

Retrieves available content templates.

Response:

{
  "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:

{
  "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:

{
  "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)

{
  "statusCode": 422,
  "message": "Validation failed",
  "error": "ValidationError",
  "data": {
    "errors": [
      {
        "field": "siteName",
        "message": "Site name is required",
        "code": "required"
      }
    ]
  }
}

Authentication Error (401)

{
  "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

curl -X GET \
  http://localhost:3000/api/dms/settings \
  -H 'Authorization: Bearer your_jwt_token' \
  -H 'Content-Type: application/json'

Update Site Settings

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

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

// 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

// 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:

{
  "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

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

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