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
id 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.