Rest Handlers

This option is used to define the rest handlers that are not generated by UCC, i.e. custom handlers developed by the user.

Example

{
  "options": {
    "restHandlers": [
      {
        "name": "StorageBuckets",
        "endpoint": "Splunk_TA_Example_buckets",
        "handlerType": "EAI",
        "resourcePresent": true,
        "registerHandler": {
          "file": "storage_buckets.py",
          "actions": ["list", "create", "remove", "edit"]
        },
        "capabilities": {
          "put": "admin_all_objects",
          "post": "list_storage_passwords"
        },
        "parentResource": "splunk_ta_uccexample",
        "requestParameters": {
          "create": {
            "param_name": {
              "required": true,
              "schema": {
                "type": "string"
              }
            }
          },
          "edit": {...},
          "remove": {...},
          "list": {...}
        },
        "responseParameters": {...}
      }
    ]
  }
}

The example above defines an EAI rest handler named StorageBuckets with the endpoint Splunk_TA_Example_buckets. UCC will modify the web.conf and restmap.conf files to register the handler. The handler file location is bin/storage_buckets.py and it will allow the actions list, create, remove, and edit. OpenApi entries will be generated for the handler with the specified request and response parameters. For example, POST requests to .../Splunk_TA_Example_buckets require a param_name parameter.

Required properties

Property	Description
name	Name of the rest handler. Used in descriptions in the OpenApi specification. Only letters, digits and underscore.
endpoint	Endpoint of the rest handler: https://<SPLUNK_URL>:<MGMT_PORT>/servicesNS/-/<app_name>/<meta.restRoot>/<ENDPOINT>. Only letters, digits and underscore.
handlerType	Type of the handler. At the moment only EAI (read more) is supported.

EAI properties (optional)

Property	Description
registerHandler	If it is specified, UCC will add proper lines to web.conf and restmap.conf. You need to specify handler file name and EAI actions. Example: {"file": "handler.py", "actions" ["create", "list"]}
requestParameters	Request parameters for each action. The parameters are used in the OpenApi specification. See below.
resourcePresent	Specifies whether the collection should expose its resources as well via web.conf or not. Default value is False.
capabilities	Specifies the capabilities required for the given methods. The provided capabilities will be generated in restmap.conf. For more information, refer to the Splunk documentation on restmap.conf.
parentResource	Specifies parent Resource for the given endpoint, it will get added in the match attribute of restmap.conf. Default value is “/.
responseParameters	Response parameters for each action. The parameters are used in the OpenApi specification. See below.

registerHandler is needed to register the handler in the web.conf and restmap.conf files.

requestParameters and responseParameters are used to define the parameters in OpenApi specification.

Request and Response parameters

The requestParameters and responseParameters objects are used to define the parameters for each action.

Allowed actions are: list, create, edit, remove.

Format

{
  "<action_name>": {
    "<param_name>": {
      "required": true,
      "schema": {...}
    }
  }
}

Property	Description
required	If true, the parameter is required. Optional, default is false
schema	Required parameter - OpenAPI schema for the parameter, as described in OAS Data Types.

Example parameters

{
  "create": {
    "param_str_required": {
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    "param_number": {
      "schema": {"type": "number"}
    },
    "param_object": {
      "schema": {
        "type": "object",
        "properties": {
          "key1": {"type": "string"},
          "key2": {"type": "number"}
        }
      }
    }
  },
  "remove": {
    "param_str_2": {
      "schema": {
        "type": "string"
      }
    }
  }
}

The example above creates the following entries in the OpenApi specification:

1. POST requests to .../Splunk_TA_Example_buckets with the following body parameters: - param_str_required is required and must be a string, - param_number is optional and must be a number, - param_object is optional and must be an object with keys key1 and key2 (e.g. {"key1": "a", "key2": 1}), - as it is an EAI handler, name is also required.
2. DELETE requests to .../Splunk_TA_Example_buckets/{name} with the following query parameters: - param_str_2 is optional and must be a string.