CRUD Settings
The Settings API supports all Create, Read, Update, and Delete (CRUD) operations relating to a setting type.
Settings changes are written to the Settings database.
CRUD operations are supported through four dedicated endpoints:
| POST/settings-objects/{settingType} |
Creates a setting for the first time. In the event a setting is deleted and a new setting is required at a later date, then it must be created via the POST endpoint. |
| PUT /settings-objects/{settingType}/{settingId} |
Update a setting that is currently "in use" or, if a scheduled setting does not already exist, then a scheduled setting can be created via this endpoint. |
| DELETE /settings-objects/{settingType}/{settingId} |
Deletes the current setting and scheduled setting (if it exists). |
| GET /settings-objects/{settingType}/{settingId} |
Retrieves information relating to the current setting. |
Features
These endpoints support two key features:
Approvals
Settings can be created, updated, or deleted with or without approvals. This functionality is already available in DPS v1. The requiresApproval field controls this behaviour, accepting true or false values.
If set to true, the setting remains inactive until it is approved.
If omitted or set to false (default), the setting becomes active immediately.
Scheduling
Settings can be created or updated with a future activeFromDate. This feature is new and was not available in DPS v1. The activeFromDate field determines whether a setting is current or scheduled:
A current setting is actively in use. To create or update a current setting, set activeFromDate to the current date-time or leave it empty (defaults to the current date-time).
A scheduled setting takes effect at a future date-time. To schedule a setting, set activeFromDate to the desired future date-time. The setting will automatically activate when the date-time is reached.
Statuses
After submitting a request to create, update, or delete a setting, one of four possible statuses may be returned:
ACTIVE – Assigned when a setting is created or updated without requiring approval. This status applies to both current and scheduled settings. Additionally, a setting also becomes active after approval of a create or update operation.
INACTIVE – Applies when a current setting is deleted without requiring approval. If approval is needed, the setting remains inactive until the deletion request is approved.
INACTIVE_APPROVAL_PENDING – Indicates that a newly created current or scheduled setting is awaiting approval before becoming active.
ACTIVE_APPROVAL_PENDING – Assigned when an update or deletion request for a current or scheduled setting is pending approval.