Skip to content

Settings_API.mdx

Latest commit

 

History

History
361 lines (262 loc) · 6.46 KB

Settings_API.mdx

File metadata and controls

361 lines (262 loc) · 6.46 KB
Raw
path docs/api/Settings_API.mdx
title System Settings API
description API reference for managing system-wide and tenant-specific configuration settings in SveltyCMS.
order 4
icon mdi:cog
author admin
created 2025-10-05
updated 2025-10-05
tags
api
settings
configuration
system
multi-tenant

System Settings API

Overview

The Settings API provides endpoints for managing system-wide configuration in SveltyCMS. All settings are stored in the database using a database-agnostic adapter, supporting multi-tenancy when enabled.

Base Path: /api/settings

Authentication

All settings endpoints require authentication:

Cookie: session=your-session-id

Most operations also require admin permissions.

Endpoints

1. Get Settings by Group

Retrieves settings for a specific configuration group.

Request

GET /api/settings/[group]

Path Parameters:

  • group (string) - Configuration group name (e.g., 'system', 'email', 'security')

Headers:

Cookie: session=your-session-id

Permissions Required: Authenticated user

Response

Success (200):

{
	"success": true,
	"data": {
		"SITE_NAME": "My CMS",
		"SITE_URL": "https://example.com",
		"MULTI_TENANT": false
	}
}

Error Responses:

// 401 Unauthorized
{
  "success": false,
  "message": "Unauthorized"
}

// 404 Not Found - Group doesn't exist
{
  "success": false,
  "message": "Settings group not found"
}

// 500 Internal Server Error
{
  "success": false,
  "message": "Failed to retrieve settings"
}

2. Update Settings

Updates one or more system settings in the database.

Request

POST /api/settings/update

Headers:

Cookie: session=your-session-id
Content-Type: application/json

Body:

{
	"SITE_NAME": "Updated Site Name",
	"SITE_URL": "https://newdomain.com",
	"MULTI_TENANT": true
}

Permissions Required: Admin user (recommended)

Response

Success (200):

{
	"success": true,
	"message": "Settings saved successfully."
}

Error Responses:

// 401 Unauthorized
{
  "success": false,
  "message": "Unauthorized"
}

// 400 Bad Request - No settings provided
{
  "success": false,
  "message": "No settings provided to update."
}

// 500 Internal Server Error
{
  "success": false,
  "message": "Failed to save settings."
}

Important Notes

  • Settings are validated before being saved
  • Cache is automatically invalidated after successful update
  • Changes take effect immediately across the system
  • Multi-tenant mode: Some settings may be tenant-specific

Common Settings Groups

System Settings (system)

{
	"SITE_NAME": "string",
	"SITE_URL": "string",
	"MULTI_TENANT": "boolean",
	"DEFAULT_LANGUAGE": "string"
}

Database Settings (database)

{
	"DB_TYPE": "mongodb | postgres | mysql",
	"DB_HOST": "string",
	"DB_PORT": "number",
	"DB_NAME": "string"
}

Email Settings (email)

{
	"SMTP_HOST": "string",
	"SMTP_PORT": "number",
	"SMTP_USER": "string",
	"SMTP_FROM": "string"
}

Security Settings (security)

{
	"SESSION_TIMEOUT": "number (minutes)",
	"PASSWORD_MIN_LENGTH": "number",
	"ENABLE_2FA": "boolean",
	"RATE_LIMIT_ENABLED": "boolean"
}

Database-Agnostic Implementation

The Settings API uses a database-agnostic adapter:

// Settings are stored and retrieved via the adapter interface
const result = await db.settings.getSettings(group);
const updateResult = await db.settings.updateSettings(settingsData);

This means you can swap databases (MongoDB, PostgreSQL, MySQL) without changing API code.

Multi-Tenancy Support

When MULTI_TENANT mode is enabled:

  • Settings can be scoped to specific tenants
  • Tenant ID is derived from subdomain or user context
  • System-wide settings override tenant-specific ones

Tenant-Specific Settings:

GET /api/settings/system
# Automatically scoped to the current tenant

Security Considerations

Sensitive Settings

Some settings contain sensitive data:

  • Database credentials
  • API keys
  • SMTP passwords
  • Encryption keys

Best Practices:

  1. Never expose sensitive settings in client-side code
  2. Use environment variables for critical secrets
  3. Implement proper role-based access control
  4. Audit all settings changes
  5. Encrypt sensitive values at rest

Settings Validation

All settings are validated before being saved:

  • Type checking (string, number, boolean)
  • Format validation (URLs, emails)
  • Range validation (min/max values)
  • Dependency validation (some settings require others)

Cache Management

Settings are cached for performance:

  • Cache Duration: Configurable (default: until invalidated)
  • Invalidation: Automatic after updates
  • Manual Invalidation: Available via internal API

Cache Behavior:

  1. First request: Load from database, cache result
  2. Subsequent requests: Serve from cache
  3. After update: Cache invalidated, next request re-loads

Testing

Manual Testing with cURL

Get Settings:

curl -X GET https://your-domain.com/api/settings/system \
  -H "Cookie: session=your-session-cookie"

Update Settings:

curl -X POST https://your-domain.com/api/settings/update \
  -H "Cookie: session=your-session-cookie" \
  -H "Content-Type: application/json" \
  -d '{
    "SITE_NAME": "My New CMS",
    "SITE_URL": "https://newdomain.com"
  }'

JavaScript Example

// Get settings
const response = await fetch('/api/settings/system', {
	credentials: 'include'
});
const { data } = await response.json();

// Update settings
const updateResponse = await fetch('/api/settings/update', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json'
	},
	credentials: 'include',
	body: JSON.stringify({
		SITE_NAME: 'Updated Name',
		MULTI_TENANT: true
	})
});

Related Documentation

Implementation Details

For implementation details, see:

  • src/routes/api/settings/update/+server.ts - Update endpoint
  • src/routes/api/settings/[group]/+server.ts - Get endpoint
  • src/stores/globalSettings.ts - Settings store and cache
  • src/databases/dbInterface.ts - Database adapter interface