Configuration API Usage Guide

Quick Usage

  1. With a user under tenant MASTER_CONFIG create a config module in YAML with POST /modules/{module} with headers Accept: text/yaml and Content-type: text/yaml. You must also have user role CMS_CONFIG_ADMIN to save.
  2. Retrieve that YAML configuration under the same user with GET /modules/{module} and Accept: text/yaml.
  3. With a different user under a different tenant (e.g. TENANT_X), retrieve the master config with GET /modules/{module} and Accept: text/yaml. The configuration will be the same as from the first step.
  4. Still under tenant TENANT_X, create a config module in YAML with POST /modules/{module} with headers Accept: text/yaml and Content-type: text/yaml. You must also have user role CMS_CONFIG_ADMIN to save.
  5. Retrieve that YAML configuration with GET /modules/{module} and Accept: text/yaml. It will be the YAML of TENANT_X, not MASTER_CONFIG.
  6. If you delete (DELETE /modules/{module}) the above module under TENANT_X, then you will still retrieve the config from MASTER_CONFIG.
  7. If the module does not exist in either MASTER_CONFIG nor TENANT_X, then a 404 response will be returned.

In-Depth Usage

Save YAML, Retrieve JSON

You can configurations in basic YAML (no fragments or aliases) with comments on their own line. Here are some examples:

YAML (PUT/POST and Content-type: text/yaml)

# This is a comment
foo: bar

JSON (GET and Accept: application/json)

{"foo": "bar"}

and

YAML (PUT/POST and Content-type: text/yaml)

# This is a comment
foo: 
  bar:
    - 1
    - 2
  # That was an array

JSON (GET and Accept: application/json)

{"foo":{"bar":[1,2]}}

Note: Comments must be treated with the same care as keys and values with respect to indentation, and must be on their own lines. Here are some examples of unacceptable YAML snippets:

foo: # This is an invalid comment (must be on a new line) 

foo:
# This is an invalid comment
  bar: 'baz' 

foo:
    # This is an invalid comment
  bar: 'baz' 

foo:
  # This is a valid comment
  bar: 'baz'

Drill Down into Configurations

You can drill down into a configuration to avoid editing and retrieving one massive configuration. Given

foo:
  bar:
    baz: 'hello'

you can query GET /modules/{module}/foo/bar (Accept: application/json) to retrieve simply

{"baz": "hello"}

Similarly with PUT, if you run PUT /modules/{module}/foo/bar with the following YAML payload

baz: 'goodbye'

and query the full YAML (Accept: text/yaml), you will get

foo:
  bar:
    baz: 'goodbye'

This makes it convenient to work with sections of a module.

History of Modules

When a PUT operation is made, a history of previous configs is appended.

  1. Under a user of a given tenant, perform GET /history/modules/{module} with Accept: text/yaml.
  2. You should get a history array similar to the following. 
     [
     {
         "id": -1,
         "timestamp": 1613069544,
         "vancouverTime": "2021-02-11T10:52:24",
         "config": "alerts:\n  table:\n    defaultSort:\n    ...",
         "sizeChars": 30894
     },
     {
         "id": 2182,
         "timestamp": 1612981332,
         "vancouverTime": "2021-02-10T10:22:12",
         "config": "alerts:\n  table:\n    defaultSort:\n    ...",
         "sizeChars": 30894
     },
    The first entry is the current configuration. Timestamps are given in two formats, the first being since epoch in seconds. The sizeChars is the length of the given configuration in ASCII characters.
  3. Without adding parameters, the max history entries returned is 100 because the response payload can grow to several megabytes otherwise.
  4. You can add the ?limit=[1..100] and ?page=[0..n] parameters to control paging.
  5. You can select a date range with ?fromDateInclusive= and ?toDateExclusive= subject to the 100 entry limit.
  6. Use epoch seconds as dates, or ISO8601 dates in the above date query parameters.
  7. By adding ?brief=true, you can get the same history array without the config fields populated, and the page limit increases to 1000 (e.g. ?limit=[1..1000]). 
     [
     {
         "id": -1,
         "timestamp": 1613069544,
         "vancouverTime": "2021-02-11T10:52:24",
         "config": null,
         "sizeChars": 30894
     },
     {
         "id": 2182,
         "timestamp": 1612981332,
         "vancouverTime": "2021-02-10T10:22:12",
         "config": null,
         "sizeChars": 30894
     },
  8. Specify ?id=n if you want to retrieve a known history entry by id.
  9. Deleting a module deletes the history of that module, so be careful.
← AuditVocalink Proxy →