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. A setting must belong to a Processing Entity, in the event a setting is created without the processingEntity defined then the owning Processing Entity will default to UNKNOWN. |
| PUT /settings-objects/{settingType}/{settingId} |
Updates a setting that is currently "in use"/active or, if a scheduled setting does not already exist, then a scheduled setting can be created via this endpoint. Requests must have the processingEntity value defined. |
| DELETE /settings-objects/{settingType}/{settingId} |
Deletes an active setting. The optional processingEntity parameter if provided in the request ensures that a Processing Entity can only delete its own settings. |
| GET /settings-objects/{settingType}/{settingId} |
Retrieves "in use"/active settings. The optional processingEntity parameter if provided in the request ensures that a Processing Entity can only retrieve its own settings. |
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.
Processing Entity Handling
A setting can only be associated with a single Processing Entity, the processingEntity value in a setting identifies the Processing Entity to which the setting applies.
Create, Read, Update, and Delete operations that have the processingEntity defined allow for restricted access based on the processingEntity value in the request and the setting’s owning Processing Entity. Calls that do not include the processingEntity do not allow for restricted based access.
| Update requests MUST always have the processingEntity defined |