Comment on page
Metadata File Configuration
This section explains the format of a Rest API metadata configuration file.
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.
{
"definitions": {
...
},
"operations": {
...
}
}
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. |
"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": {
...
}
}
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. |
"parameters": [
{
"name": "AccessKey",
"in": "path",
"type": "string",
"required": true
},
{
"name": "City",
"in": "path",
"type": "string",
"required": true
}
]
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.
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 )" }) |
"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": {
...
}
}
}
}
}
Last modified 8mo ago