Configuration

The configuration API, accessible by only super-admin requests, is used to define dynamic configurations. Dynamic configuration is needed in situations like

RSA key pair generated automatically at boot time if not present
service-specific subscription confirmation request message template

Model Schema

The API operates on following configuration data model fields:

Name

Attributes

config id

type	string, format depends on db
auto-generated	true

name

config name

type	string
required	true

value

config value.

type	object
required	true

serviceName

name of the service the config applicable to

type	string
required	false

Get Configurations

GET /configurations

permissions required, one of
- super admin
- admin
inputs
- a filter containing properties where, fields, order, skip, and limit
  - parameter name: filter
  - required: false
  - parameter type: query
  - data type: object
  The filter can be expressed as either
  1. URL-encoded stringified JSON object (see example below); or
  2. in the format supported by qs, for example ?filter[where][created][$gte]="2023-01-01"&filter[where][created][$lt]="2024-01-01"
  Regardless, the filter will have to be parsed into a JSON object conforming to
```
{
    "where": {...},
    "fields": ...,
    "order": ...,
    "skip": ...,
    "limit": ...,
}
```
  All properties are optional. The syntax for each property is documented, respectively
  - for where , see MongoDB Query Documents
  - for fields , see Mongoose select
  - for order, see Mongoose sort
  - for skip, see MongoDB cursor.skip
  - for limit, see MongoDB cursor.limit
outcome
For admin request, a list of config items matching the filter; forbidden for user request

example

to retrieve configs created in year 2023, run

curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/configurations?filter=%7B%22where%22%3A%7B%22created%22%3A%7B%22%24gte%22%3A%222023-01-01%22%2C%22%24lt%22%3A%222024-01-01%22%7D%7D%7D'

the value of the filter query parameter is URL-encoded stringified JSON object

{
  "where": {
    "created": {
      "$gte": "2023-01-01",
      "$lt": "2024-01-01"
    }
  }
}

Create a Configuration

POST /configurations

permissions required, one of
- super admin
- admin
inputs
- an object containing configuration data model fields. At a minimum all required fields that don't have a default value must be supplied. Id field should be omitted since it's auto-generated. The API explorer only created an empty object for field value but you should populate the child fields.
  - parameter name: data
  - required: true
  - parameter type: body
  - data type: object
outcome
NotifyBC performs following actions in sequence
1. if it’s a user request, error is returned
2. inputs are validated. For example, required fields without default values must be populated. If validation fails, error is returned
3. if config item is notification with field value.rss populated, and if the field value.httpHost is missing, it is generated using this request's HTTP protocol , host name and port.
4. item is saved to database

example
see the cURL command on how to create a dynamic subscription config

Update a Configuration

PATCH /configurations/{id}

permissions required, one of
- super admin
- admin
inputs
- configuration id
  - parameter name: id
  - required: true
  - parameter type: path
  - data type: string
- an object containing fields to be updated.
  - parameter name: data
  - required: true
  - parameter type: body
  - data type: object
outcome
Similar to POST except field update is always updated with current timestamp.

Update Configurations

PATCH /configurations

permissions required, one of
- super admin
- admin
inputs
- a where query parameter with value conforming to MongoDB Query Documents
  - parameter name: where
  - required: false
  - parameter type: query
  - data type: object
  The value can be expressed as either
  1. URL-encoded stringified JSON object (see example below); or
  2. in the format supported by qs, for example ?where[created][$gte]="2023-01-01"&where[created][$lt]="2024-01-01"
- an object containing fields to be updated.
  - required: true
  - parameter type: body
  - data type: object
outcome
Similar to POST except field update is always updated with current timestamp.

example

to set serviceName to myService for all configs created in year 2023 , run

curl -X PATCH --header 'Content-Type: application/json' 'http://localhost:3000/api/configurations?where=%7B%22created%22%3A%7B%22%24gte%22%3A%222023-01-01%22%2C%22%24lt%22%3A%222024-01-01%22%7D%7D' -d @- << EOF
{
  "serviceName": "myService",
}
EOF

the value of the where query parameter is URL-encoded stringified JSON object

{
  "created": {
    "$gte": "2023-01-01",
    "$lt": "2024-01-01"
  }
}

Delete a Configuration

DELETE /configurations/{id}

permissions required, one of
- super admin
- admin
inputs
- configuration id
  - parameter name: id
  - required: true
  - parameter type: path
  - data type: string
outcome
For admin request, delete the config item requested; forbidden for user request

Replace a Configuration

PUT /configurations/{id}

This API is intended to be only used by admin web console to modify a configuration.

permissions required, one of
- super admin
- admin
inputs
- configuration id
  - parameter name: id
  - required: true
  - parameter type: path
  - data type: string
- configuration data
  - parameter name: data
  - required: true
  - parameter type: body
  - data type: object
outcome
For admin requests, replace configuration identified by id with parameter data and save to database.