Metadata File Configuration

This section explains the format of a Boon Amber Metadata File configuration.

Structure

The metadata configuration file should conform to a particular schema, which comprises two main objects: "definitions" and "operations". The Operations Object describes the REST operation, and the Definitions Object describes the input and output schemas referenced to these operations.

Example:

{
    "definitions": {
        ...
    },
    "operations": {
        ...
    }
}

Operations Object

The Operations Object describes the operations that would be displayed in the Operation dropdown under the Operation section of the Agents' configuration blade. This object contains one or more operations specified as key-value pairs (separated by comma), where the key is the name of the REST operation, which should be unique, and the value is an object that contains several properties that describe the REST operation, as explained below.

PropertyRequiredTypeProperty Value

endPoint

Required

string

Relative path to an individual endpoint of the REST API. This path is appended to the base URL to construct full URL of the API.

method

Required

string

Value to specify the operation type. The options are GET, POST, PUT, DELETE.

description

Required

string

Text which describes the operation.

contentType

Optional

string

The type of the content. Possible values are "application/json" (default) and "multipart/formdata"

parameters

Optional

array

JSON array of input parameters. Only required when the operation requires any input. Refer to Parameters Object for more details.

responseSchema

Optional (Required for Context Provider)

string

Name of the response schema. This should match the name of one of the items specified under the Definitions Object. Required when the operation has a response.

Example:

"operations": {
		"Get Sensors": {
			"endPoint": "/v1/sensors",
			"method": "GET",
			"description": "Get sensors",
			"contentType": "application/json",
			"responseSchema": "Root"
		}
		"Post Stream": {
			"endPoint": "/v1/stream",
			"method": "POST",
			"description": "Get stream",
			"contentType": "application/json",
			"parameters": [
				{
					"name": "sensorId",
					"in": "header",
					"type": "string",
					"required": true
				},
				{
					"name": "postStreamRequest",
					"in": "body",
					"type": "object",
					"required": true,
					"schema": "streamRequest"
				}
			],
			"responseSchema": "RawJSON"
		}
	}

Parameters Object

The Parameters Object describes the input parameters that are required by the REST operation. This object is of type JSON array in which each item describes one parameter. The parameters will be displayed in the Input Mapping section of the Agents' configuration blade. Each parameter object has several properties, as explained below.

PropertyRequiredTypeProperty Value

name

Required

string

Name of the parameter. This value is case-sensitive and must be unique.

in

Required

string

Specifies the location of the parameter being used. Possible values are "header" (use as HTTP request header), "path" (Replace the endPoint relative path {(Parameter name)} with the value), "body" (send in the HTTP request body), "formdata" (send as HTTP formdata)

type

Required

string

JSON data type that denotes the type of the parameter's value. Value can be specified as "file" when the REST operation requires a file as input, in which case the value of "in" property should be "formdata"

required

Optional

string

Specifies whether this parameter is required or not. Defaulted to false if not specified.

schema

Optional

string

Required when the parameter type is an object and the value of the "in" property is "body".

This indicates the schema of the body and should match the name of one of the items specified under the Definitions Object.

Example:

//For endPoint: /v1/rootCause?pattern={pattern}&clusterId={clusterID}
"parameters": [
	{
		"name": "sensorId",
		"in": "header",
		"type": "string",
		"required": true
	},
	{
		"name": "clusterID",
		"in": "path",
		"type": "string",
		"required": true
	},
	{
		"name": "pattern",
		"in": "path",
		"type": "string",
		"required": true
	}
]

//For endPoint: /v1/stream
"parameters": [
	{
		"name": "sensorId",
		"in": "header",
		"type": "string",
		"required": true
	},
	{
		"name": "postStreamRequest",
		"in": "body",
		"type": "object",
		"required": true,
		"schema": "streamRequest"
	}
]

Definitions Object

The Definitions Object describes the definition of schema referred to the Operations object's responseSchema property. This object contains one or more definitions specified as key-value pairs separated by commas, where the "key" is the name of the schema which must be unique and the "value" is an object that contains several properties that describe the schema, as explained below.

The value must conform to Newtonsoft JSON Schema specifications.

PropertyRequiredTypeProperty Value

title

Required

string

Short text that describes the schema.

description

Optional

string

Text that describes the schema.

type

Required

string

JSON data type that denotes the type of the parameter's value. Possible options are "object", "array", and "string". Selecting "string" type will output the raw response message from the Rest API.

properties

Optional

object

Required when the definition type is "object". Comma separated key-value pairs that define the properties of the schema, where the key is the name of the property and the value is an object which defines the schema of the property. Use "format"="date" or "date-time" and "pattern"="<date/time format>" to format properties that contain date or datetime values.

items

Optional

object

Required when the definition type is "array". Defines the schema of a single item of the array. This schema definition can be specified inline as another definition object or as a reference to one of the definition object already specified using "$ref" property. (e.g. "items":{

"$ref":"#/definitions/(Key of the schema )"

})

Example:

"definitions": {
    	"Root": {
		"title": "Root",
		"type": "array",
		"items": {
			"$ref": "#/definitions/Sensor"
		}
	},
	"Sensor": {
		"title": "Sensor",
		"type": "object",
		"properties": {
			"label": {
				"type": "string"
			},
			"sensorId": {
				"type": "string"
			}
		},
		"required": [
			"label",
			"sensorId"
		]
	},
	"RawJSON": {
		"title": "RawJSON",
		"type": "string"
	},
	"streamRequest": {
		"title": "streamRequest",
		"type": "object",
		"properties": {
			"data": {
				"type": "string"
			},
		},
		"required": [
			"data",
		]
	}
}

Last updated