Description
Limitations
- Only JSON based REST APIs are supported
Release Notes
| Version: | 3.03 |
| Released: | 13-Aug-2018 |
| Release Notes: | Fixed the date parsing issue and metadata file refresh issue |
| Version | Released | Release Notes |
| 3.02 | 13-Aug-2018 | Added OnError endpoint |
| 3.01 | 07-Aug-2018 | Removed SSL3 protocol support |
| 3.0 | 03-Aug-2018 | Initial Release |
Configuration
To add the REST API action agent to a stream, follow the steps below:
- Ensure you have a use case open in the stream designer, this can be a new use case or an existing use case
- From the toolbox on the left expand the Action Agents option and scroll down until you can see “REST API”
- You can also use the search in the header to find the stream object quickly
- Click and drag the REST API action agent from the toolbox onto the canvas
- Rename the action agent by clicking into the text area to the right of the icon
- Save the stream by clicking the save button in the action bar
- Hover over the icon for the stream object until it turns orange and then double click to open the configuration page
- You can also click on the configure option in the action bar after selecting the stream object
- Configuration options
- The Collection drop down allows you to associate this stream object with a specific collection. The selected option would be, by default, the same as the collection that was selected for the use case. If you do need to change it to another collection, select a different collection from the drop down.
- Service Details options
- Add a base URL, for example “https://maximo-demo76.mro.com/maximo/oslc/os/”
- Upload a JSON metadata file by clicking on the Select File button and browsing to the file.
- If required, select the Use Authentication check box.
- If you selected Use Authentication check box, specify a username and password.
- Operation options
- Select a value from the Operation drop down, for example “Create Asset”.
- Click Apply on the action bar, and then save the stream using the Save button.
Metadata File Specifications
The metadata JSON file should conform to a particular schema, which comprises of two main objects: “definitions” and “operations”. The operations object describes the REST operations and the definitions object describes the input and output schemas referenced to by these operations.
Example:
{
“definitions”: {
………
},
“operations”: {
………
}
}
The operations object describes the operations that are displayed in the list of allowed operations in the Integration Wizard when using this agent. 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 describes the REST operation, as explained below:
| Property Name | 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. Possible values are GET, POST, PUT, DELETE. |
| description | Required | string | Text which describes the operation. |
| contentType | Optional | string | 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 | 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 Asset By ID”: {
“endPoint”: “/Asset?id={AssetID}”,
“method”: “GET”,
“description”: “Gets a list of Assets”,
“parameters”: [
{
“name”: “X-APIKEY”,
“in”: “header”,
“type”: “string”,
“required”: true
},
{
“name”: “AssetID”,
“in”: “path”,
“type”: “string”,
“required”: true
}
],
“responseSchema”: “PlantSet”
},
“Get Customers”: {
…………
}
}
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. Each Parameter object has several properties, as explained below.
| Property Name | Required | Type | Property Value |
| name | Required | string | Name of the parameter. This value is case-sensitive and should be unique. |
| in | Required | string | Specifies the location of the parameter. Possible values are “header”, “path”, “body”, “formdata”. |
| type | Required | string | JSON data type that denotes the type of the property’s value. Value can be specified as “file” when the REST operation requires a file as input, in which case the value of the “in” property should be “formdata”. |
| required | Optional | boolean | Specifies whether this parameter is required or not. The default value is false. If this value is true, the mapped XMPro form control will also be set to Required = true. |
| schema | Optional | string | Required when the parameter type is an object and the value of the “in” property is “body”. |
Example:
“parameters”: [
{
“name”: “X-APIKEY”,
“in”: “header”,
“type”: “string”,
“required”: true
},
{
“name”: “ID”,
“in”: “path”,
“type”: “string”,
“required”: true
},
{
“name”: “Announcement”,
“in”: “body”,
“type”: “object”,
“schema”: “NewAnnouncement”
}]
The definitions object describes the definition of schemas referred to in the Operations object. This object contains one or more definitions specified as key-value pairs (separated by comma), where the key is the name of the schema, which should be unique, and the value is an object that contains several properties that describe the schema, as explained below. The value should conform to the Newtonsoft Json Schema specifications.
| Property Name | 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 property’s value. Possible options are “object”, “array”. |
| 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. (refer to examples for syntax) |
| 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 objects already specified using the “$ref” property (refer to example below for syntax). |
Example:
“definitions”: {
“Announcement”: {
“title”: “Announcement”,
“description”: “Announcement”,
“type”: “object”,
“properties”: {
“id”: {
“type”: “string”
},
“type”: {
“type”: “string”
},
“priority”: {
“type”: “string”
},
“status”: {
“type”: “string”
}
}
},
“AnnouncementList”: {
“title”: “Announcement List”,
“description”: “Announcement List”,
“type”: “array”,
“items”: {
“$ref”: “#/definitions/Announcement”
}
},
“announcementModels”: {
“title”: “AnnouncementModels”,
“type”: “array”,
“items”: {
“title”: “AnnouncementModels”,
“type”: “object”,
“properties”: {
“modelID”: {
“type”: “string”
},
“modelName”: {
“type”: “string”
},
“modelClass”: {
“type”: “string”
}
}
}
}
}