Web services - remiges-tech/rigel GitHub Wiki

/schemalist

This web service provides a list of all schemas i.e. combinations of applications, modules, and versions.

Request

This is a simple GET request.

No request parameters are needed for this call, as it is designed to fetch a comprehensive list of all schemas without any specific filtering.

Processing

Upon receiving a GET request to this endpoint, the Rigel service performs the following steps:

  1. Query the etcd Store: The service queries the etcd store to retrieve all keys that match the schema pattern (e.g., /remiges/rigel/[AppName]/[ModuleName]/[VersionNumber]/schemas).

  2. Extract Schema Information: From each key, the service extracts the app name, module name, and version number, compiling this information into a structured format.

  3. Create Response Array: The extracted schema details are assembled into an array. Each element in the array represents a unique combination of app, module, and version.

  4. Format and Send Response: The array is wrapped in a JSON object and sent back as the response to the request.

Response

{
  "schemas": [
    {
      "app": "FinanceApp",
      "module": "PaymentGateway",
      "ver": 2,
      "description": "Configuration schema of the PaymentGateway module in FinanceApp."
    },
    {
      "app": "FinanceApp",
      "module": "AccountingModule",
      "ver": 3,
      "description": "Configuration schema of the AccountingModule in FinanceApp."
    },
    {
      "app": "SocialApp",
      "module": "UserProfile",
      "ver": 1,
      "description": "Configuration schema of the UserProfile module in SocialApp."
    }
  ]
}

If there are no schemas present an empty array will be sent.

/schemaget

The /schemaget web service call is designed to retrieve detailed information about a specific schema within the Rigel service. This call provides the structure and attributes of the schema for a given app, module, and version.

Request

  1. App (required): The name of the application.
  2. Module (required): The name of the module within the application.
  3. Ver (required): The version number of the module.

The request would typically be structured as a query string attached to the endpoint URL.

Example Request URL

GET /api/v1/schemaget?app=FinanceApp&module=PaymentGateway&ver=2

Processing

Upon receiving a request, the Rigel service:

  1. Validates Parameters: Checks if the provided app, module, and version parameters are valid and not empty.

  2. Fetches Schema Details: Retrieves the schema details for the specified app, module, and version from the etcd store.

  3. Formats the Response: Organizes the fetched schema data into the response structure and sends it back to the client.

Response

The response will be a JSON object representing the schema's structure, including field definitions and metadata such as a description or creation/update timestamps.

{
  "app": "FinanceApp",
  "module": "PaymentGateway",
  "ver": 2,
  "fields": [
    {
      "name": "transactionTimeout",
      "type": "int",
      "description": "Defines the maximum duration (in seconds) a transaction should take before timing out.",
      "constraints": {
        "min": 1, 
        "max": 60
      }
    },
    {
      "name": "SessionTimeout",
      "type": "float",
      "description": "Maximum time taken (in seconds) for session time out in floating-point number.",
      "constraints": {
        "min": 1.5,
        "max": 59.5
      }
    },
    {
      "name": "currencyType",
      "type": "string",
      "description": "Specifies the type of currency used for transactions, e.g., USD, EUR.",
      "constraints": {
        "enum": ["USD", "INR", "SGD"]
      }
    }
  ],
  "description": "Configuration schema of the PaymentGateway module in FinanceApp."
}

Errors

  • schema_not_found: The specified schema does not exist.

/configset

Sets a single configuration parameter value for a given schema and configuration instance.

Request

{
    "app": "FinanceApp",
    "module": "PaymentGateway",
    "ver": 2,
    "config": "ProdConfig",
    "key": "transactionTimeout",
    "value": 30
}
  • name: string, required. The name of the configuration parameter to set.
  • value: varies, required. The new value for the configuration parameter. The type and constraints of this value must align with the schema definition.

Processing

Upon receiving a POST request to this endpoint, the Rigel service performs the following steps:

  • Ensure that all required parameters are provided and valid.
  • Check that the specified schema (app, module, ver) and configuration exists.
  • Verify that the name and value are compatible with the schema definition.
  • If all checks pass, update the specified configuration parameter in the etcd store.

Response

The response will be an empty response in the standard response format.

Errors

schema_not_found: The specified schema does not exist. config_not_found: The specified configuration instance does not exist. invalid_key: The specified parameter name does not match the schema. invalid_val: The type of the provided value does not match the expected type in the schema. out_of_range: The provided value violates defined constraints in the schema (if any). Corresponding field name would be set in error message.

/confighist

Gets the change data for a single configuration parameter value for a given schema and configuration instance.

Request

{
    "app": "FinanceApp",
    "module": "PaymentGateway",
    "ver": 2,
    "config": "ProdConfig",
    "key": "transactionTimeout"
}

where all the parameters specify one configuration parameter whose change-data is to be fetched.

Processing

Upon receiving a POST request to this endpoint, the Rigel service performs the following steps:

  • Ensure that all required parameters are provided and valid.
  • Check that the specified schema (app, module, ver) and configuration exists.
  • Verify that the name is present in the schema
  • If all checks pass, pull out the change-data for the parameter from the .../[VersionNumber]/hist/ tree of keys. (Actual values are stored under .../[VersionNumber]/config/ tree.)

Response

The response will be a JSON array of the following form

{
    "app": "FinanceApp",
    "module": "PaymentGateway",
    "ver": 2,
    "config": "ProdConfig",
    "name": "transactionTimeout",
    "value": 30",
    "description": "Change-data history for FinanceApp/PaymentGateway/2/ProdConfig/transactionTimeout",
    "hist": [{
        "who": "[email protected]",
        "when": "2023-04-09T04:09:05Z",
        "val": "25"
    },{
        "who": "[email protected]",
        "when": "2023-05-10T03:23:45Z",
        "val": "28"
    },{
        "who": "[email protected]",
        "when": "2024-01-23T10:52:02Z",
        "val": "30"
    }]
}

where

  • the hist array will have at least one element, because the original value of the parameter will have resulted in one entry
  • the val elements will always be of type string, because Rigel internally stores all values as strings
  • the value in the field value will always match the value of the val field of the last element
  • the entries in the array will be sorted in ascending order of time, where the most recent entry will be the last element
  • the who fields in hist will have the username string as obtained from the JWT used to authenticate access to Rigel when the value was updated, or SYSTEM if the value was set from the command-line tool (initial load).
  • the when fields in hist will have timestamps in UTC

Errors

  • schema_not_found: The specified schema does not exist.
  • config_not_found: The specified configuration instance does not exist.
  • missing: The parameter name given in the request does not exist under this combination of (app,module,version,config)

/configupdate

Sets multiple configuration values based on a given schema and version. It allows for different configuration instances (configName) for a specific schema (appName and moduleName combination).

Request

POST /configupdate

{
    "app": "FinanceApp",
    "module": "PaymentGateway",
    "ver": 2,
    "config": "ProdConfig",
    "description": "Configuration schema of the PaymentGateway module in FinanceApp.",
    "values": [
      {"name": "transactionTimeout", "value": 5},
      {"name": "sessionTimeout", "value": 5.51},
      {"name": "currencyType", "value": "USD"},
    ]
}
  • app: The name of the application.
  • module: The name of the module within the application.
  • ver: The version number of the schema.
  • config: The name of the specific configuration instance (e.g., UAT, Europe).
  • values: object, required. Key-value pairs of configuration parameters and their values. These parameters must be present in the schema and the value type must match as per the schema specification.

Response

The response will be an empty response in the standard response format.

Errors

  • schema_not_found: Schema with the specified name and version does not exist.
  • invalid_key: One or more parameter names do not match the schema. vals will contain the name of the invalid parameter
  • invalid_val: One or more values do not match the type defined in the schema. vals will contain the name of the failed param and value.

/configlist

This web service provides a list of all configurations for a schema (app, module and version combination).

Request

GET /configlist

This web service will expect appName, moduleName and versionNumber in the query string. All the fields are mandatory.

Example:

GET /configlist?app=FinanceApp&module=PaymentGateway&ver=2

Processing

Upon receiving a GET request to this endpoint, the Rigel service performs the following steps:

  • Retrieve Configurations
    • Fetches all named configurations from the etcd store.
    • The keys are expected to be structured as /remiges/rigel/[AppName]/[ModuleName]/[VersionNumber]/[ConfigName]

Response

{
    "configurations": [
        {
            "app": "FinanceApp",
            "module": "PaymentGateway",
            "ver": 2,
            "config": "ProdConfig",
        },
        {
            "app": "FinanceApp",
            "module": "PaymentGateway",
            "ver": 2,
            "config": "TestConfig",
        },
    ]
}

Errors

  • app_not_found: The specified application does not exist.
  • module_not_found: The specified module does not exist within the application.
  • ver_not_found: The specified version of the module does not exist.

/configget

Retrieves all configuration parameters for a given schema and configuration instance.

Request

Endpoint:

GET /configget

Query Parameters:

  • app: The name of the application.
  • module: The name of the module within the application.
  • version: The version number of the schema.
  • config: The name of the specific configuration instance (e.g., UAT, Europe).
GET /configget?app=FinanceApp&module=PaymentGateway&ver=2&config=ProdConfig

Processing

Upon receiving a GET request to this endpoint, the Rigel service performs the following steps:

  • Validate that all required query parameters (appName, moduleName, versionNumber, namedConfig) are provided and correctly formatted. Existence Check:

  • Check if the specified application, module, and version exist in the system. Verify that the configuration (e.g., ProdConfig) exists for the given app-module-version tuple. Data Retrieval:

  • Retrieve the configuration data from the etcd store, using a key structured as /remiges/rigel/[AppName]/[ModuleName]/[VersionNumber]/[ConfigName].

  • Format the retrieved data into a structured JSON response, listing each configuration field and its value. Error Handling:

If any of the checks or retrieval steps fail, return an appropriate error code and message (e.g., APP_NOT_FOUND, MODULE_NOT_FOUND).

Response

{
    "app": "FinanceApp",
    "module": "PaymentGateway",
    "ver": 2,
    "config": "ProdConfig",
    "description": "Configuration for prod config of the PaymentGateway module in FinanceApp.",
    "values": [
        {
            "name": "transactionTimeout",
            "value": 30
        },
        {
            "name": "defaultCurrency",
            "value": "USD"
        }
    ]
}

Errors

  • app_not_found: The specified application does not exist.
  • module_not_found: The specified module does not exist within the application.
  • ver_not_found: The specified version of the module does not exist.
  • config_not_found: The specified configuration instance does not exist.