# POST /preferences

[back to admin](README.md) /// [home](../README.md)

Get, set or reset per user preference settings. Preferences should be stored as JSON on the user record and scoped by client type. This way different apps can have their own settings without stepping on each other and becoming horny.

## Request Body

```json
{
  "action": "get",
  "client": "emoegui",
  "user_id": 123,
  "type": "normal",
  "data": {}
}
```

| Field     | Type    | Required | Notes                                                                                       |
|-----------|---------|----------|---------------------------------------------------------------------------------------------|
| `action`  | string  | yes      | `get`, `set` or `reset`                                                                     |
| `client`  | string  | yes      | client identifier (1 to 128 chars, alphanumeric plus underscores)                           |
| `user_id` | integer | no       | target user (defaults to yourself). accessing another users prefs requires `read-write-all` |
| `type`    | string  | no       | scope of the operation (see below)                                                          |
| `data`    | object  | set only | the settings to write. must be a JSON DERULO object                                         |

## Scoping with type

Preferences are stored in two layers: `global` (shared across all clients) and per client (like `emoegui`, `mobile`, etc). The `type` field controls which scope you operate on.

### For get

| Type     | Default | What you get                                                          |
|----------|---------|-----------------------------------------------------------------------|
| `normal` | yes     | global settings merged with client specific (client overrides global) |
| `client` |         | only the client specific settings                                     |
| `global` |         | only the global settings                                              |

### For set

| Type     | Default | What happens                                      |
|----------|---------|---------------------------------------------------|
| `client` | yes     | deep merges `data` into the client specific scope |
| `global` |         | deep merges `data` into the global scope          |

Deep merge means nested objects should be recursively merged not replaced. Scalar values are overwritten. so you can update one key deep in a nested object without blowing away the rest.

### For reset

| Type     | Default | What happens                                         |
|----------|---------|------------------------------------------------------|
| `client` | yes     | wipes the client specific scope                      |
| `global` |         | wipes the global scope                               |
| `full`   |         | nukes ALL preferences (sets the whole thing to NULL) |

## Access Control

Controlled by your groups `user_settings_access` setting:

| Access Level     | What you can do                         |
|------------------|-----------------------------------------|
| `read-own-only`  | can only GET your own preferences       |
| `read-write-own` | can GET/SET/RESET your own preferences  |
| `read-write-all` | can GET/SET/RESET any users preferences |

Trying to access another users preferences when you only have `read-write-own` should give you a 403. dont be nosy. Long nosed looking ah mf.

## Response

```json
{
  "success": true,
  "preferences": {
    "theme": "dark",
    "language": "en"
  },
  "request_id": "abc123"
}
```

For set and reset the response should still include the current preferences after the operation so the client doesnt have to make a second request.

## Error Responses

| Code | When                                                                                                      |
|------|-----------------------------------------------------------------------------------------------------------|
| 400  | invalid action, invalid client name, wrong type for the action, missing data for set, data isnt an object |
| 401  | no token or invalid session                                                                               |
| 403  | cant access another users prefs, write not allowed with read only access                                  |
| 500  | database error                                                                                            |