Metadata File Configuration

This section explains the format of a Rest API metadata configuration file.

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.

Property	Required	Type	Property 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 REST API.
method	Required	string	Value to specify the operation type. The options are GET, POST, PUT, DELETE.
description	Required	string	Text which descibes 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 Current Weather": {
			"endPoint": "/current?access_key={AccessKey}&query={City}",
			"method": "GET",
			"description": "Get current weather by city",
			"parameters": [
				{
					"name": "AccessKey",
					"in": "path",
					"type": "string",
					"required": true
				},
				{
					"name": "City",
					"in": "path",
					"type": "string",
					"required": true
				}
			],
			"responseSchema": "Root"
		},
		"Get Location Details": {
			...
		}
	}

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 parameter will be displayed in the Input Mapping section of the Agents' configuration blade. Each parameter object has several properties, as explained below.

Property	Required	Type	Property 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:

"parameters": [
	{
		"name": "AccessKey",
		"in": "path",
		"type": "string",
		"required": true
	},
	{
		"name": "City",
		"in": "path",
		"type": "string",
		"required": true
	}
]

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.

Property	Required	Type	Property 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": "object",
			"properties": {
				"request": {
					"$id": "#root/request",
					"title": "Request",
					"type": "object",
					"properties": {
						"type": {
							"$id": "#root/request/type",
							"title": "Type",
							"type": "string",
							"default": "",
							"examples": [
								"City"
							],
							"pattern": "^.*$"
						},
						"query": {
							"$id": "#root/request/query",
							"title": "Query",
							"type": "string",
							"default": "",
							"examples": [
								"Sydney, Australia"
							],
							"pattern": "^.*$"
						},
						"language": {
							"$id": "#root/request/language",
							"title": "Language",
							"type": "string",
							"default": "",
							"examples": [
								"en"
							],
							"pattern": "^.*$"
						},
						"unit": {
							"$id": "#root/request/unit",
							"title": "Unit",
							"type": "string",
							"default": "",
							"examples": [
								"m"
							],
							"pattern": "^.*$"
						}
					}
				},
				"location": {
					"$id": "#root/location",
					"title": "Location",
					"type": "object",
					"properties": {
						...
					}
				},
				"current": {
					"$id": "#root/current",
					"title": "Current",
					"type": "object",
					"properties": {
						...
					}
				}
			}
		}
	}