/api/system/theme

Description

The /api/system/theme endpoint manages the custom theme configuration file stored at Data/Themes/custom_theme.txt. This endpoint allows you to read the current theme settings (GET) or update them with new configuration (POST). The theme file can contain any text-based configuration for customizing the user interface, such as color schemes, font preferences, or layout settings.

HTTP Methods

GET Request

Read the current theme configuration.

Parameters

No parameters required for GET requests.

GET Response

Returns a JSON object containing the theme file information.

GET Example Response

{
  "success": true,
  "command": "get-theme",
  "file": "custom_theme.txt",
  "path": "Data/Themes/custom_theme.txt",
  "content": "# Custom Theme Configuration\n# Add your theme settings here\n",
  "size": 68,
  "exists": false
}

POST Request

Update the theme configuration file with new content.

Request Body

Send the new theme configuration as the raw POST body. The content can be any text format (plain text, JSON, INI, etc.).

POST Parameters

POST Response

Returns a JSON object confirming the update.

POST Example Response

{
  "success": true,
  "command": "update-theme",
  "file": "custom_theme.txt",
  "path": "Data/Themes/custom_theme.txt",
  "bytes_written": 250,
  "message": "Theme configuration updated successfully"
}

Error Responses

Code Examples

cURL - GET Theme

curl http://127.0.0.1:8080/api/system/theme

cURL - POST Theme (Plain Text)

curl -X POST \
  -H "Content-Type: text/plain" \
  -d "theme: dark
colors:
  primary: #3498db
  secondary: #2ecc71
  background: #2c3e50
font: Roboto" \
  http://127.0.0.1:8080/api/system/theme

cURL - POST Theme (JSON Format)

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "theme": "dark",
  "colors": {
    "primary": "#3498db",
    "secondary": "#2ecc71",
    "background": "#2c3e50"
  },
  "font": "Roboto"
}' \
  http://127.0.0.1:8080/api/system/theme

JavaScript/Fetch - GET Theme

fetch('http://127.0.0.1:8080/api/system/theme')
  .then(response => response.json())
  .then(data => {
    console.log('Theme content:', data.content);
    console.log('File size:', data.size, 'bytes');
  })
  .catch(error => console.error('Error:', error));

JavaScript/Fetch - POST Theme

const themeConfig = `theme: dark
colors:
  primary: #3498db
  secondary: #2ecc71
  background: #2c3e50
font: Roboto`;

fetch('http://127.0.0.1:8080/api/system/theme', {
  method: 'POST',
  headers: {
    'Content-Type': 'text/plain'
  },
  body: themeConfig
})
  .then(response => response.json())
  .then(data => {
    console.log('Update successful:', data.message);
    console.log('Bytes written:', data.bytes_written);
  })
  .catch(error => console.error('Error:', error));

Python - GET Theme

import requests

response = requests.get('http://127.0.0.1:8080/api/system/theme')
data = response.json()

print(f"Theme content:\n{data['content']}")
print(f"File size: {data['size']} bytes")
print(f"File exists: {data['exists']}")

Python - POST Theme

import requests

theme_config = """theme: dark
colors:
  primary: #3498db
  secondary: #2ecc71
  background: #2c3e50
font: Roboto"""

response = requests.post(
    'http://127.0.0.1:8080/api/system/theme',
    data=theme_config,
    headers={'Content-Type': 'text/plain'}
)

data = response.json()
print(f"Update successful: {data['message']}")
print(f"Bytes written: {data['bytes_written']}")

Theme File Format

The theme configuration file supports any text-based format. Here are common approaches:

Option 1: YAML-Style (Recommended)

# Custom Theme Configuration
theme: dark
colors:
  primary: #3498db
  secondary: #2ecc71
  background: #2c3e50
  text: #ecf0f1
font:
  family: Roboto
  size: 14px
layout:
  sidebar_width: 250px
  header_height: 60px

Option 2: JSON Format

{
  "theme": "dark",
  "colors": {
    "primary": "#3498db",
    "secondary": "#2ecc71",
    "background": "#2c3e50",
    "text": "#ecf0f1"
  },
  "font": {
    "family": "Roboto",
    "size": "14px"
  },
  "layout": {
    "sidebar_width": "250px",
    "header_height": "60px"
  }
}

Option 3: INI/Properties Style

# Custom Theme Configuration
[theme]
mode=dark

[colors]
primary=#3498db
secondary=#2ecc71
background=#2c3e50
text=#ecf0f1

[font]
family=Roboto
size=14px

[layout]
sidebar_width=250px
header_height=60px

Security Considerations

• Fixed File Path: The theme file is always stored at Data/Themes/custom_theme.txt. Users cannot specify arbitrary file paths, preventing directory traversal attacks.
• Size Limit: The 8 KB maximum size prevents denial-of-service attacks through large file uploads.
• No Execution: The theme file is read and returned as plain text only. No code execution occurs.
• Text Only: Only text-based content is supported. Binary files are not processed.

Best Practices

• Version Control: Consider adding a version field to your theme configuration for easier management.
• Comments: Use comments (# for YAML/INI, // for JSON-like) to document your theme settings.
• Validation: Validate theme content on the client side before sending to ensure correct format.
• Backup: Store a backup of your theme configuration before making changes.
• Size Awareness: Monitor theme file size to stay well under the 8 KB limit.
• Default Values: Include default values in your application for when theme file doesn't exist or is invalid.

Related Endpoints

• GET /api/system/status - Get program status and version
• GET /api/system/config/usb - Check if running from USB
• GET /api/system/config/mobile - Check if running on mobile