Generic Config Store API — API Analysis (API-A)

Concept layer — frozen. The Config Store generic. Nothing here is written by a normal playbook run; a project's own feature analysis is the live document and takes every edit. This layer names no project and links to none — the dependency runs one way, from an application to its concept.

Feature: Config Store · Entity: configStore · Enum:ConfigValueType

Paths below are written without any version or gateway prefix: how a project versions and mounts the routes is an application decision, not part of the concept. Success envelope: { data, status, message, requestId }.

---

1. Get Configuration

Endpoint: GET /config?configCodes=$configCodes&active=$active

Description

Returns a flat key–value mapping of active configuration settings. Results are optionally filtered by key prefix.

Request Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Query Parameters

Parameter	Type	Required	Description
configCodes	String[]	No	Filter configStore by one or more configCode values
active	Boolean	No	Filter configStore by active

Request Logic

Validates each property according to its configValueType — see Enum — ConfigValueType.

SELECT c.configCode, c.configValue, c.configValueType
FROM configStore c
WHERE configCode = ANY(:configCodes)
  AND active = :active
  AND deletedAt IS NULL

Success Response (200 OK)

{
  "data": {
    "config.someCode": "SomeValue",
    "config.someOthercode": "https://app.example.com",
    "config.branding": {
      "branding": {
        "name": "Example Corp",
        "primaryColor": "#1E90FF"
      }
    }
  },
  "status": 200,
  "message": "Configuration values retrieved successfully.",
  "requestId": "a8123fa1-2045-42b4-83fc-97dafe11f4a5"
}

---

2. Create Configuration

Endpoint: POST /config

Description

Creates new configuration settings. Admin-only endpoint. All values are validated against their declared configValueType.

Request Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body

{
  "configCode": "config.privacyPolicyUrl",
  "configValueType": "url",
  "configValue": "https://example.com/privacy",
  "active": true
}

Request Parameters

Field	Type	Required	Description
configCode	String	Yes	Key of the config setting
configValueType	String	Yes	Expected type — see Enum — ConfigValueType
configValue	String	Yes	Value to store (type-validated)
active	Boolean	Yes	If the value is active

Request Logic

Validates each property according to its configValueType — see Enum — ConfigValueType.

Success Response (201 Created)

{
  "data": {
    "id": "018fa51f-fda1-79f4-8461-2cb8f1cabc10",
    "configCode": "config.privacyPolicyUrl",
    "configValue": "https://example.com/privacy"
  },
  "status": 201,
  "message": "Configuration created.",
  "requestId": "3ab34d88-65d1-4c10-897a-237c9a5b116f"
}

---

3. Update Configuration

Endpoint: PATCH /config

Description

Updates existing configuration values. Validates the updated value against its declared configValueType.

Request Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body

{
  "id": "some_uuidv7",
  "configCode": "config.branding",
  "configValue": "{\"branding\":{\"name\":\"Example Corp\",\"primaryColor\":\"#123456\"}}",
  "configValueType": "json",
  "active": false
}

Request Parameters

Field	Type	Required	Description
id	UUID v7	Yes	ID
configCode	String	Yes	Existing key to update
configValue	String	Yes	Updated value
configValueType	String	Yes	Updated config value type — see Enum — ConfigValueType
active	Boolean	Yes	Updated active flag

Request Logic

Validates each property according to its configValueType — see Enum — ConfigValueType. configValue is always a string; a structured value is stored serialised under the json type, and the type check parses it.

Success Response (200 OK)

{
  "data": {
    "configCode": "config.branding",
    "configValue": "{\"branding\":{\"name\":\"Example Corp\",\"primaryColor\":\"#123456\"}}",
    "configValueType": "json",
    "active": false
  },
  "status": 200,
  "message": "Configuration updated.",
  "requestId": "ad9cd51f-d993-4014-a2b2-8f563fe887fd"
}

---

4. Delete Configuration

Endpoint: DELETE /config

Single entity. The read filters the table, so it takes a list; create, update and delete act on one entity, so they take one identifier. The source concept described this delete as acting on "one or multiple config entries by configCode" while its body carried a single id — corrected here to single-entity, which is also what the implementing project does.

Description

Soft-deletes one configuration entry by id.

Request Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body

{
  "id": "some_uuid"
}

Request Parameters

Field	Type	Required	Description
id	UUID	Yes	ID to delete

Success Response (200 OK)

{
  "data": {},
  "status": 200,
  "message": "Configuration entry deleted.",
  "requestId": "16ddc487-1092-496e-b9a4-97d3e3082ee6"
}