|
|
The settings api allows clients to get and set settings in the user account.
|
|
|
|
|
|
# Contents
|
|
|
[[_TOC_]]
|
|
|
|
|
|
# Available api actions
|
|
|
| Action | Url | Method | Session required | Description |
|
|
|
| --- | --- | --- | --- | --- |
|
|
|
| [get](#the-get-action) | `/api/1.0/settings/get` | POST | no | Returns the value of one setting |
|
|
|
| [set](#the-set-action) | `/api/1.0/settings/set` | POST | yes | Sets the value of a setting |
|
|
|
| [list](#the-list-action) | `/api/1.0/settings/list` | GET | no | Lists all settings |
|
|
|
| [list](#the-list-action) | `/api/1.0/settings/list` | POST | no | Lists all settings in a scope |
|
|
|
| [reset](#the-reset-action) | `/api/1.0/settings/reset` | POST | yes | Resets a setting |
|
|
|
| Action | Url | Method | Description |
|
|
|
|-----------------------------------------------|---------------------------|------------|-------------------------------|
|
|
|
| [get](./Settings-API/Settings-Get-Action) | `/api/1.0/settings/get` | POST | Returns the value of settings |
|
|
|
| [set](./Settings-API/Settings-Set-Action) | `/api/1.0/settings/set` | POST | Sets the value of a setting |
|
|
|
| [list](./Settings-API/Settings-List-Action) | `/api/1.0/settings/list` | GET & POST | Lists settings |
|
|
|
| [reset](./Settings-API/Settings-Reset-Action) | `/api/1.0/settings/reset` | POST | Resets a setting |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# Scopes and Settings
|
|
|
| Scope | Writable | Description |
|
|
|
| --- | --- | --- |
|
|
|
|--------|----------|--------------------------------------------------------------------------------|
|
|
|
| user | yes | Settings for the current user account. Used to configure backend/api behaviour |
|
|
|
| client | yes | Client settings. Accessible to all clients attached to the user account |
|
|
|
| server | no | Server settings, configured by the admin |
|
|
|
|
|
|
| Setting | Type | Default | Description |
|
|
|
| --- | --- | --- | --- |
|
|
|
|-----------------------------------|--------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
|
| user.password.generator.strength | int | 1 | The strength of generated passwords, a value between 0 (weak) and 4 (strong) |
|
|
|
| user.password.generator.numbers | bool | false | Whether or not generated passwords contain numbers |
|
|
|
| user.password.generator.special | bool | false | Whether or not generated passwords contain special characters |
|
... | ... | @@ -67,96 +69,9 @@ The settings api allows clients to get and set settings in the user account. |
|
|
|
|
|
|
|
|
|
|
|
# The get action
|
|
|
The get action retrieves the value of one or more settings.
|
|
|
This action accepts an array of strings where each value is the name of one setting.
|
|
|
|
|
|
#### Arguments
|
|
|
| Arguments | Type | Default | Required | Description |
|
|
|
| --- | --- | --- | --- | --- |
|
|
|
| first setting | string | - | yes | The name of the first setting |
|
|
|
| second setting | string | - | no | The name of the second setting |
|
|
|
|
|
|
#### Return value
|
|
|
The success status code is `200 Ok`.
|
|
|
The return value is an object with the requested settings.
|
|
|
Each key of the object is a setting and the value is the value of the setting.
|
|
|
|
|
|
#### Notes
|
|
|
- The Enhanced API also offers the option to get a single setting
|
|
|
- If the setting is not defined, it will default to `null`
|
|
|
- Accessing an undefined setting in the `client` scope will not create it
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# The set action
|
|
|
The set action updates the value of one or more settings.
|
|
|
This action accepts an object where each key is the name of a setting and the value is the new value
|
|
|
|
|
|
#### Arguments
|
|
|
| Arguments | Type | Default | Required | Description |
|
|
|
| --- | --- | --- | --- | --- |
|
|
|
| first setting | mixed | - | yes | The first setting to be set |
|
|
|
| second setting | mixed | - | no | The second setting to be set |
|
|
|
|
|
|
#### Return value
|
|
|
The success status code is `200 Ok`.
|
|
|
The return value is an object with the updated settings and their new value.
|
|
|
|
|
|
#### Notes
|
|
|
- The Enhanced API also offers the option to set a single setting
|
|
|
- If the scope is not writable, the setting will not be saved and default to `null` in the return value
|
|
|
- If the setting is not defined in the `user` scope, it will not be saved and default to `null` in the return value
|
|
|
- If the size limitations of the `client` scope are exceeded, an error will be returned
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# The reset action
|
|
|
The reset actionwill reset the value of one or more settings to the default.
|
|
|
This action accepts an array of strings where each value is the name of one setting.
|
|
|
|
|
|
#### Arguments
|
|
|
| Arguments | Type | Default | Required | Description |
|
|
|
| --- | --- | --- | --- | --- |
|
|
|
| first setting | string | - | yes | The name of the first setting |
|
|
|
| second setting | string | - | no | The name of the second setting |
|
|
|
|
|
|
#### Return value
|
|
|
The success status code is `200 Ok`.
|
|
|
The return value is an object with the cleared settings.
|
|
|
Each key of the object is a setting and the value is the value of the setting.
|
|
|
|
|
|
#### Notes
|
|
|
- If you reset a setting in the client scope, it will be deleted and no longer appear in the list action
|
|
|
- If the setting does not exist, the value will be `null`
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# The list action
|
|
|
The list action returns all settings or the settings within a scope if one is given.
|
|
|
|
|
|
#### Arguments
|
|
|
| Arguments | Type | Default | Required | Description |
|
|
|
| --- | --- | --- | --- | --- |
|
|
|
| scopes | array | - | no | An array with the names of all requested scopes as value |
|
|
|
|
|
|
#### Return value
|
|
|
The return value is a JSON formatted object with all settings from the requested scopes.
|
|
|
|
|
|
#### Notes
|
|
|
- If a scope has been specified, only the values of this scope will be returned
|
|
|
- If the specified scopes do not exist, te return value is an empty array
|
|
|
- If no scope has been defined, all existing settings will be returned
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# Known client settings
|
|
|
| Setting | Type | Default | Allowed Values | Description |
|
|
|
| --- | --- | --- | --- | --- |
|
|
|
|-------------------------------------|--------|------------|-------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
|
|
|
| client.ui.section.default | string | `all` | `all`, `favorites`, `folders`, `tags`, `recent` | Which section to show when the app ist loaded |
|
|
|
| client.ui.password.field.title | string | `label` | `label`, `website` | Which field to use as title of a password |
|
|
|
| client.ui.password.field.sorting | string | `byTitle` | `byTitle`, `label`, `website` | Sort passwords by this field instead of the label. `byTitle` means use the `title` setting |
|
... | ... | |