Comment on page

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": {
						...
					}
				}
			}
		}
	}

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.

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.

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 )" })

Action Agent - Previous

Release Notes

Last modified 8mo ago