API For System Configuration
solaris007 opened this issue · comments
We have recently introduced a a system-wide configuration (see schema), used by the jobs-dispatcher but expandable for arbitrary system-wide configuration.
Currently such configuration has to be set directly in the database. The desire is to make updating/creating configuration accessible via HTTP API as per the latest architecture council discussion.
Here's an API proposal:
openapi: 3.0.0
info:
title: Configuration Management API
description: API to manage application-wide configurations, including retrieval of the current, specific versions, and the latest configurations, as well as updating existing configurations.
version: 1.0.0
servers:
- url: https://api.yourdomain.com/v1
description: Production server
paths:
/configurations:
get:
summary: Get all application configurations
operationId: getAllConfigurations
responses:
'200':
description: A list of all known configurations or empty list if no configurations are present.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Configuration'
/configurations/latest:
get:
summary: Get the latest application configuration
operationId: getLatestConfiguration
responses:
'200':
description: The latest application configuration.
content:
application/json:
schema:
$ref: '#/components/schemas/Configuration'
'404':
description: Latest configuration not found.
put:
summary: Update the configuration, creating a new configuration version
operationId: updateConfiguration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationUpdate'
responses:
'200':
description: Configuration updated successfully.
'400':
description: Invalid request format.
'404':
description: Configuration not found.
/configurations/{version}:
get:
summary: Get a specific version of the application configuration
operationId: getConfigurationByVersion
parameters:
- name: version
in: path
required: true
schema:
type: string
responses:
'200':
description: Specific version of the application configuration.
content:
application/json:
schema:
$ref: '#/components/schemas/Configuration'
'404':
description: Configuration not found.
components:
schemas:
Configuration:
type: object
properties:
version:
type: string
readOnly: true
description: Internal version of the configuration, managed and incremented by the system. Not exposed for external control via the API.
jobs:
type: array
items:
$ref: '#/components/schemas/Job'
description: A list of job configurations, detailing job type, its group, and execution interval.
queues:
type: object
properties:
audits:
type: string
format: url
description: The SQS queue name for audit jobs
imports:
type: string
format: url
description: The SQS queue name for import jobs
reports:
type: string
format: url
description: The SQS queue name for report jobs
Job:
type: object
properties:
group:
type: string
description: The group or category to which the job belongs, helping in organizing jobs by their functional area.
interval:
type: string
description: Specifies how often the job should run, e.g., 'daily'. This is part of job scheduling information.
type:
type: string
description: The job type, indicating the specific action or task that the job performs, such as 'rum-to-aa' indicating a data import job from RUM to AA.
ConfigurationUpdate:
type: object
properties:
jobs:
type: array
items:
$ref: '#/components/schemas/Job'
description: Optional. Provide to update the job configurations.
queues:
type: object
properties:
audits:
type: string
format: url
description: Optional. Provide to update the SQS queue name for audit jobs.
imports:
type: string
format: url
description: Optional. Provide to update the SQS queue name for import jobs.
reports:
type: string
format: url
description: Optional. Provide to update the SQS queue name for report jobs.@iuliag @ekremney @dzehnder @alinarublea @blefebvre please review
Hi, @solaris007, to make create configuration available, should we add a POST method to the /configurations path? Thanks!
@solaris007 regarding the PUT /configurations/{version} endpoint:
- Does it have to be called with a full payload containing all configurations, or only the part of it that the consumer wants to add/update?
- Would the consumer of this endpoint need to calculate the next version? Would any version parameter work?
getAllConfigurations should return an empty array instead of status code 404 if no configurations were found?
This would return all existing versions of the configuration or what do you mean by all known configurations?
What's the idea behind the versioning?
When you update a specific version of the configuration, is that creating a new version? My understanding is that a configuration with a certain version, once created, is immutable.
Do we need to expose it in the API - can't we just have it behind the scenes for auditing reasons, if needed, and never expose it?
@iuliag - thanks for your input. indeed, will change to return an empty array for the collection endpoint.
yes, the idea is that configs are immutable, i.e. updating a config would create a new version. in light of this, do you think the spec is accurate or needs amendment?
@AndreiAlexandruParaschiv since we're creating new versions of the config via updating, i don't think we ever actually create a version
yes, the idea is that configs are immutable, i.e. updating a config would create a new version. in light of this, do you think the spec is accurate or needs amendment?
I think the spec needs some amendments so that it's not creating confusions.
I'd show the version only in the responses and have the update endpoint only on the latest version with no need from the consumer to specify a version.
regarding the update payload, i did not really think about it. would you prefer a merge or full updating? @iuliag?
At this point, any would work. The not obvious part for the merge is: how do you clear some values?
put:
summary: Update the configuration, creating a new configuration version
operationId: updateConfiguration
parameters:
- name: version
Regarding @ekremney's comment, the spec reads like the PUT endpoint requires a version parameter in the path. Should this be removed from the put: method spec?
regarding the update payload, i did not really think about it. would you prefer a merge or full updating?
It's concerning that a user has to resubmit configurations for audits/reports A, B, and C when all they want to do is create a new configuration for audit/report D. There's a risk of human error leading to the corruption or deletion of all other audit/report configurations
added #193
added #198
🎉 This issue has been resolved in version 1.26.0 🎉
The release is available on:
v1.26.0- GitHub release
Your semantic-release bot 📦🚀