Admin Settings API Endpoints

[Aniol0012]

Admin Settings API Endpoints

Important

Implement whatever it is duable, so if any can not be implemented easly, just prioritize the other stuff that can be easly implemented. It is important to have at least the easy part done.

Description

This document specifies the required endpoints to implement the Admin Settings functionality on the backend.

All endpoints described here are restricted to users with the Admin role.

---

Table of Contents

• Security
• Endpoints
  • Get System Settings
  • Update System Settings
  • Send Test Email
  • Clear Cache
• Data Models
• Implementation Notes
• Implementation Checklist
• References

---

Security

All endpoints in this section:

• Are accessible only to users with the Admin role
• Must return 403 Forbidden if the user is not an administrator

Authentication mechanism is assumed to be handled globally by the platform.

---

Endpoints

1. Get System Settings

Returns the current system configuration.

GET /admin/settings

{
  "system": {
    "maintenanceMode": false,
    "allowNewRegistrations": true,
    "requireEmailVerification": true,
    "maxUploadSizeMb": 10,
    "sessionTimeoutMinutes": 120,
    "defaultLanguage": "ca",
    "emailNotifications": true,
    "pushNotifications": true,
    "autoModeration": false,
    "maxImagesPerPost": 10
  },
  "security": {
    "passwordMinLength": 8,
    "passwordRequireUppercase": true,
    "passwordRequireNumbers": true,
    "passwordRequireSpecialChars": false,
    "maxLoginAttempts": 5,
    "accountLockoutMinutes": 30,
    "twoFactorAuthEnabled": false
  },
  "content": {
    "allowAnonymousPosts": false,
    "requirePostApproval": false,
    "maxPostLength": 5000,
    "allowExternalLinks": true,
    "profanityFilterEnabled": true,
    "minReportThreshold": 3
  },
  "notifications": {
    "emailFrom": "noreply@unihub.smuks.dev",
    "emailReplyTo": "support@unihub.smuks.dev",
    "smtpServer": "smtp.gmail.com",
    "smtpPort": 587,
    "smtpUsername": "username@gmail.com",
    "smtpPassword": "********"
  }
}

Possible Errors

• 403 Forbidden: User is not an admin
• 500 Internal Server Error: Server error

2. Update System Settings

Updates system configuration. Only the fields that need to be changed must be sent

PUT /admin/settings

Request Body

{  "system": {    "maintenanceMode": false,
    "allowNewRegistrations": true,
    "requireEmailVerification": true,
    "maxUploadSizeMb": 10,
    "sessionTimeoutMinutes": 120,
    "defaultLanguage": "ca",
    "emailNotifications": true,
    "pushNotifications": true,
    "autoModeration": false,
    "maxImagesPerPost": 10
  },
  "security": {
    "passwordMinLength": 8,
    "passwordRequireUppercase": true,
    "passwordRequireNumbers": true,
    "passwordRequireSpecialChars": false,
    "maxLoginAttempts": 5,
    "accountLockoutMinutes": 30,
    "twoFactorAuthEnabled": false
  },
  "content": {
    "allowAnonymousPosts": false,
    "requirePostApproval": false,
    "maxPostLength": 5000,
    "allowExternalLinks": true,
    "profanityFilterEnabled": true,
    "minReportThreshold": 3
  },
  "notifications": {
    "emailFrom": "noreply@unihub.smuks.dev",
    "emailReplyTo": "support@unihub.smuks.dev",
    "smtpServer": "smtp.gmail.com",
    "smtpPort": 587,
    "smtpUsername": "username@gmail.com",
    "smtpPassword": "password123"
  }
}

Successful Response (200 OK)

{
  "message": "Settings updated successfully",
  "settings": {
    "system": {},
    "security": {},
    "content": {},
    "notifications": {}
  }
}

Validations

• system.maxUploadSizeMb: 1–100
• system.sessionTimeoutMinutes: 5–1440
• system.maxImagesPerPost: 1–20
• system.defaultLanguage: ca, es, en
• security.passwordMinLength: 6–20
• security.maxLoginAttempts: 3–10
• security.accountLockoutMinutes: 5–1440
• content.maxPostLength: 100–10000
• content.minReportThreshold: 1–10
• notifications.smtpPort: 1–65535

Possible Errors

• 400 Bad Request: Validation error
• 403 Forbidden: User is not an admin
• 500 Internal Server Error: Server error

---

3. Send Test Email

Sends a test email using the current SMTP configuration.

POST /admin/settings/test-email

{
  "email": "admin@example.com"
}

Parameters

Field	Type	Required	Description
email	string	Yes	Recipient of the test email

Successful Response (200 OK)

{
  "message":"Test email sent successfully",
  "recipient":"admin@example.com",
  "sentAt":"2025-12-27T10:30:00Z"
}

Email Content

Subject:UniHub - Email Configuration Test

This is a test email from UniHub Admin Settings.

If you received this email, your SMTP configuration is working correctly.

Sent at:2025-12-27 10:30:00 UTC

Possible Errors

-400 Bad Request:Invalid email
-403 Forbidden:User is not an admin
-500 Internal Server Error:SMTP error

---

4.Clear Cache

Clears all system cache(Redis,application cache,etc.).

POST /admin/cache/clear

Request Body

{}

Successful Response (200 OK)

{
  "message":"Cache cleared successfully",
  "clearedAt":"2025-12-27T10:30:00Z",
  "details":{
    "redis":true,
    "applicationCache":true,
    "cdnCache":false
  }
}

Possible Errors

-403 Forbidden:User is not an admin
-500 Internal Server Error:Server error

---

Data Models

SystemSettings

{
  maintenanceMode:boolean;
  allowNewRegistrations:boolean;
  requireEmailVerification:boolean;
  maxUploadSizeMb:number;
  sessionTimeoutMinutes:number;
  defaultLanguage:string;
  emailNotifications:boolean;
  pushNotifications:boolean;
  autoModeration:boolean;
  maxImagesPerPost:number;
}

SecuritySettings

{
  passwordMinLength:number;
  passwordRequireUppercase:boolean;
  passwordRequireNumbers:boolean;
  passwordRequireSpecialChars:boolean;
  maxLoginAttempts:number;
  accountLockoutMinutes:number;
  twoFactorAuthEnabled:boolean;
}

ContentSettings

{
  allowAnonymousPosts:boolean;
  requirePostApproval:boolean;
  maxPostLength:number;
  allowExternalLinks:boolean;
  profanityFilterEnabled:boolean;
  minReportThreshold:number;
}

NotificationSettings

{
  emailFrom:string;
  emailReplyTo:string;
  smtpServer:string;
  smtpPort:number;
  smtpUsername:string;
  smtpPassword:string;
}

---

Implementation Notes

Storage

-Settings should be persisted in the database
-Recommended approach:system_settingstable using key–value or grouped JSON
-Alternative:persistent configuration file

Security

-SMTP password must never be returned in plain text
-Mask the password in GET responses
-Update SMTP password only if a new one is provided

Cache

-Cache must be invalidated automatically after updating settings
-Using cache is recommended to avoid frequent database reads

Validation

-All defined validations must be applied before persisting changes
-Validation errors should clearly indicate which field failed

Auditing

-It is strongly recommended to log all configuration changes,including:
-Admin user
-Timestamp
-Previous values
-New values
-Request IP

Implementation Scope

-All features described in this document must be implemented whenever possible
-If a specific feature is technically too complex or unfeasible,the rest of the functionality must still be fully implemented

---

Implementation Checklist

-Create system settings table/model
-Implement GET /admin/settings
-Implement PUT /admin/settings
-Implement POST /admin/settings/test-email
-Implement POST /admin/cache/clear
-Enforce Admin role checks
-Apply all validations
-Mask SMTP password on GET
-Configure email service
-Implement caching strategy
-Implement audit logging
-Unit tests
-Integration tests
-API documentation(Swagger/OpenAPI)

---

References

-Main API documentation:https://api.unihub.smuks.dev/docs#/
-Frontend component: /apps/uniroom/src/app/admin/settings/