Settings

The Settings API allows you to manage system configuration settings. Settings are stored as key-value pairs and can be used to configure various aspects of the application behavior.

List Settings

Retrieve all system settings.

Endpoint

GET /v1/settings/

Authentication

This endpoint requires authentication with a valid Bearer token.

Example Request

curl -X GET https://fav3.vibemobi.com/v1/settings/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

[
    {
        "key": "cool_off_days",
        "value": "14",
        "description": "Number of days for favorite number cooloff period",
        "id": 1,
        "created_at": "2023-12-01T10:00:00Z",
        "updated_at": "2023-12-01T10:00:00Z"
    },
    {
        "key": "max_favorites_per_customer",
        "value": "5",
        "description": "Maximum number of favorite numbers per customer",
        "id": 2,
        "created_at": "2023-12-01T10:00:00Z",
        "updated_at": "2023-12-01T10:00:00Z"
    },
    {
        "key": "api_rate_limit",
        "value": "100",
        "description": "API rate limit per minute per user",
        "id": 3,
        "created_at": "2023-12-01T10:00:00Z",
        "updated_at": "2023-12-01T10:00:00Z"
    }
]

Create Setting

Create a new system setting.

Endpoint

POST /v1/settings/

Authentication

This endpoint requires authentication with a valid Bearer token.

Request Body

Parameter	Type	Required	Description
key	`string`	Yes	Unique setting key (e.g., 'cool_off_days')
value	`string`	Yes	Setting value (stored as string, convert in code if needed)
description	`string`	No	Optional description of the setting

Example Request

curl -X POST https://fav3.vibemobi.com/v1/settings/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "key": "notification_enabled",
    "value": "true",
    "description": "Enable or disable system notifications"
  }'

Response

{
    "key": "notification_enabled",
    "value": "true",
    "description": "Enable or disable system notifications",
    "id": 4,
    "created_at": "2023-12-01T15:30:00Z",
    "updated_at": "2023-12-01T15:30:00Z"
}

Error Responses

Duplicate Key

{
    "detail": "Setting with this key already exists"
}

Get Setting by Key

Retrieve a specific setting by its key.

Endpoint

GET /v1/settings/{key}

Authentication

This endpoint requires authentication with a valid Bearer token.

Path Parameters

Parameter	Type	Required	Description
key	`string`	Yes	Setting key

Example Request

curl -X GET https://fav3.vibemobi.com/v1/settings/cool_off_days \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

{
    "key": "cool_off_days",
    "value": "14",
    "description": "Number of days for favorite number cooloff period",
    "id": 1,
    "created_at": "2023-12-01T10:00:00Z",
    "updated_at": "2023-12-01T10:00:00Z"
}

Error Responses

Setting Not Found

{
    "detail": "Setting not found"
}

Update Setting

Update an existing setting's value or description.

Endpoint

PUT /v1/settings/{key}

Authentication

This endpoint requires authentication with a valid Bearer token.

Path Parameters

Parameter	Type	Required	Description
key	`string`	Yes	Setting key

Request Body

Parameter	Type	Required	Description
value	`string`	No	New setting value
description	`string`	No	New description

Example Request

curl -X PUT https://fav3.vibemobi.com/v1/settings/cool_off_days \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "value": "21",
    "description": "Extended cooloff period for favorite numbers"
  }'

Response

{
    "key": "cool_off_days",
    "value": "21",
    "description": "Extended cooloff period for favorite numbers",
    "id": 1,
    "created_at": "2023-12-01T10:00:00Z",
    "updated_at": "2023-12-01T16:45:00Z"
}

Error Responses

Setting Not Found

{
    "detail": "Setting not found"
}

Delete Setting

Delete a setting by its key.

Endpoint

DELETE /v1/settings/{key}

Authentication

This endpoint requires authentication with a valid Bearer token.

Path Parameters

Parameter	Type	Required	Description
key	`string`	Yes	Setting key

Example Request

curl -X DELETE https://fav3.vibemobi.com/v1/settings/notification_enabled \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

Returns an empty response with status code 200.

Error Responses

Setting Not Found

{
    "detail": "Setting not found"
}

Common Settings

Here are some commonly used settings in the VibeMobi system:

Favorite Number Settings

Key	Default Value	Description
`cool_off_days`	`14`	Number of days for favorite number cooloff period
`max_favorites_per_customer`	`5`	Maximum number of favorite numbers per customer
`allow_duplicate_favorites`	`false`	Whether to allow duplicate favorite numbers

API Configuration

Key	Default Value	Description
`api_rate_limit`	`100`	API rate limit per minute per user
`max_request_size`	`1048576`	Maximum request size in bytes (1MB)
`session_timeout`	`3600`	Session timeout in seconds (1 hour)

Notification Settings

Key	Default Value	Description
`notification_enabled`	`true`	Enable or disable system notifications
`email_notifications`	`true`	Enable email notifications
`sms_notifications`	`false`	Enable SMS notifications

System Configuration

Key	Default Value	Description
`maintenance_mode`	`false`	Enable maintenance mode
`debug_mode`	`false`	Enable debug logging
`backup_retention_days`	`30`	Number of days to retain backups

Data Types and Conversion

Settings are stored as strings but may represent different data types:

Boolean Values

{
    "key": "notification_enabled",
    "value": "true"  // Convert to boolean in application code
}

Numeric Values

{
    "key": "cool_off_days",
    "value": "14"  // Convert to integer in application code
}

JSON Values

{
    "key": "email_config",
    "value": "{\"smtp_host\":\"smtp.example.com\",\"port\":587}"  // Parse JSON in application code
}

Best Practices

Setting Management Best Practices

Key Naming - Use descriptive, lowercase keys with underscores - Group related settings with prefixes (e.g., email_, api_) - Avoid spaces and special characters in keys

Value Storage - Store all values as strings for consistency - Perform type conversion in application code - Use JSON strings for complex data structures

Documentation - Always provide meaningful descriptions - Document expected value formats and ranges - Include default values in descriptions

Security - Never store sensitive data (passwords, API keys) in settings - Use environment variables or secure vaults for secrets - Consider encryption for sensitive configuration data

Important Considerations

Application Restart - Some settings may require application restart to take effect - Check application documentation for restart requirements

Validation - Settings are not validated at the API level - Implement validation in your application code - Invalid settings may cause application errors

Backup - Regularly backup your settings configuration - Test setting changes in development environments first - Keep track of setting changes for rollback purposes

Setting Categories

Runtime Settings

Settings that take effect immediately without restart: - cool_off_days - max_favorites_per_customer - notification_enabled

Configuration Settings

Settings that may require restart or reload: - api_rate_limit - session_timeout - debug_mode

Feature Flags

Settings used to enable/disable features: - maintenance_mode - email_notifications - sms_notifications

Bulk Operations

For bulk setting operations, use multiple API calls:

```bash

Example: Update multiple settings

settings=( "cool_off_days:21" "max_favorites_per_customer:10" "notification_enabled:false" )

for setting in "${settings[@]}"; do key="${setting%%:}" value="${setting##:}" curl -X PUT "https://fav3.vibemobi.com/v1/settings/$key" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d "{\"value\":\"$value\"}" done