admin/preferences.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90


POST /preferences
back to admin /// home
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
{
  "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
{
  "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