REST Data Connector
Manage Settings
Obtain a license for the REST service and configure the default values for REST in Manage > Settings > Rest.
Note: If the OAuth Client Id has a value, then all REST extensions for that named set will use OAuth.
SmartIQ also implements REST Data Connections, supporting POST and GET methods. Similarly, as JSON Data Connections, it is required to define available filter and display fields. In this case, this could be achieved using swagger that allows adding as many Data Objects as methods available for an API or via JSON Schemas, however, it is required to create a new Data Connection per Method.
Read and Write API Support
In order to write data back to an API, only JSON Schema is supported. You can use OpenAPI to read and JSON Schema to write but you will have to write and maintain two different schema definitions.
Key Concepts
Swagger Specification (OpenAPI) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
For more information, refer to Swagger (OpenAPI) Specification.
The REST data connection supports swagger with the syntax swagger=[url] in the connection string.
swagger=[url]
Example:
swagger=file:///c:\temp\petStore.json
Swagger Definition Example
{
"swagger": "2.0",
"info": {
"description": "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.",
"version": "1.0.0",
"title": "Swagger Petstore",
"termsOfService": "http://swagger.io/terms/",
"contact": { "email": "[email protected]" },
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"host": "petstore.swagger.io",
"basePath": "/v2",
"tags": [
{
"name": "pet",
"description": "Everything about your Pets",
"externalDocs": {
"description": "Find out more",
"url": "http://swagger.io"
}
},
{
"name": "store",
"description": "Access to Petstore orders"
},
{
"name": "user",
"description": "Operations about user",
"externalDocs": {
"description": "Find out more about our store",
"url": "http://swagger.io"
}
}
],
"schemes": [ "http" ],
"paths": {
"/pet": {
"post": {
"tags": [ "pet" ],
"summary": "Add a new pet to the store",
"description": "",
"operationId": "addPet",
"consumes": [ "application/json", "application/xml" ],
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"in": "body",
"name": "body",
"description": "Pet object that needs to be added to the store",
"required": true,
"schema": { "$ref": "#/definitions/Pet" }
}
],
"responses": { "405": { "description": "Invalid input" } }
},
"put": {
"tags": [ "pet" ],
"summary": "Update an existing pet",
"description": "",
"operationId": "updatePet",
"consumes": [ "application/json", "application/xml" ],
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"in": "body",
"name": "body",
"description": "Pet object that needs to be added to the store",
"required": true,
"schema": { "$ref": "#/definitions/Pet" }
}
],
"responses": {
"400": { "description": "Invalid ID supplied" },
"404": { "description": "Pet not found" },
"405": { "description": "Validation exception" }
}
}
},
"/pet/findByStatus": {
"get": {
"tags": [ "pet" ],
"summary": "Finds Pets by status",
"description": "Multiple status values can be provided with comma separated strings",
"operationId": "findPetsByStatus",
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"name": "status",
"in": "query",
"description": "Status values that need to be considered for filter",
"required": true,
"type": "array",
"items": {
"type": "string",
"enum": [ "available", "pending", "sold" ],
"default": "available"
},
"collectionFormat": "multi"
}
],
"responses": {
"200": {
"description": "successful operation",
"schema": {
"type": "array",
"items": { "$ref": "#/definitions/Pet" }
}
},
"400": { "description": "Invalid status value" }
}
}
},
"/pet/findByTags": {
"get": {
"tags": [ "pet" ],
"summary": "Finds Pets by tags",
"description": "Muliple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.",
"operationId": "findPetsByTags",
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"name": "tags",
"in": "query",
"description": "Tags to filter by",
"required": true,
"type": "array",
"items": { "type": "string" },
"collectionFormat": "multi"
}
],
"responses": {
"200": {
"description": "successful operation",
"schema": {
"type": "array",
"items": { "$ref": "#/definitions/Pet" }
}
},
"400": { "description": "Invalid tag value" }
},
"deprecated": true
}
},
"/pet/{petId}": {
"get": {
"tags": [ "pet" ],
"summary": "Find pet by ID",
"description": "Returns a single pet",
"operationId": "getPetById",
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"name": "petId",
"in": "path",
"description": "ID of pet to return",
"required": true,
"type": "integer",
"format": "int64"
}
],
"responses": {
"200": {
"description": "successful operation",
"schema": { "$ref": "#/definitions/Pet" }
},
"400": { "description": "Invalid ID supplied" },
"404": { "description": "Pet not found" }
},
"security": [ { "api_key": [ ] } ]
},
"post": {
"tags": [ "pet" ],
"summary": "Updates a pet in the store with form data",
"description": "",
"operationId": "updatePetWithForm",
"consumes": [ "application/x-www-form-urlencoded" ],
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"name": "petId",
"in": "path",
"description": "ID of pet that needs to be updated",
"required": true,
"type": "integer",
"format": "int64"
},
{
"name": "name",
"in": "formData",
"description": "Updated name of the pet",
"required": false,
"type": "string"
},
{
"name": "status",
"in": "formData",
"description": "Updated status of the pet",
"required": false,
"type": "string"
}
],
"responses": { "405": { "description": "Invalid input" } }
},
"delete": {
"tags": [ "pet" ],
"summary": "Deletes a pet",
"description": "",
"operationId": "deletePet",
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"name": "api_key",
"in": "header",
"required": false,
"type": "string"
},
{
"name": "petId",
"in": "path",
"description": "Pet id to delete",
"required": true,
"type": "integer",
"format": "int64"
}
],
"responses": {
"400": { "description": "Invalid ID supplied" },
"404": { "description": "Pet not found" }
}
}
},
"/pet/{petId}/uploadImage": {
"post": {
"tags": [ "pet" ],
"summary": "uploads an image",
"description": "",
"operationId": "uploadFile",
"consumes": [ "multipart/form-data" ],
"produces": [ "application/json" ],
"parameters": [
{
"name": "petId",
"in": "path",
"description": "ID of pet to update",
"required": true,
"type": "integer",
"format": "int64"
},
{
"name": "additionalMetadata",
"in": "formData",
"description": "Additional data to pass to server",
"required": false,
"type": "string"
},
{
"name": "file",
"in": "formData",
"description": "file to upload",
"required": false,
"type": "file"
}
],
"responses": {
"200": {
"description": "successful operation",
"schema": { "$ref": "#/definitions/ApiResponse" }
}
}
}
},
"/store/inventory": {
"get": {
"tags": [ "store" ],
"summary": "Returns pet inventories by status",
"description": "Returns a map of status codes to quantities",
"operationId": "getInventory",
"produces": [ "application/json" ],
"parameters": [ ],
"responses": {
"200": {
"description": "successful operation",
"schema": {
"type": "object",
"additionalProperties": {
"type": "integer",
"format": "int32"
}
}
}
},
"security": [ { "api_key": [ ] } ]
}
},
"/store/order": {
"post": {
"tags": [ "store" ],
"summary": "Place an order for a pet",
"description": "",
"operationId": "placeOrder",
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"in": "body",
"name": "body",
"description": "order placed for purchasing the pet",
"required": true,
"schema": { "$ref": "#/definitions/Order" }
}
],
"responses": {
"200": {
"description": "successful operation",
"schema": { "$ref": "#/definitions/Order" }
},
"400": { "description": "Invalid Order" }
}
}
},
"/store/order/{orderId}": {
"get": {
"tags": [ "store" ],
"summary": "Find purchase order by ID",
"description": "For valid response try integer IDs with value >= 1 and <= 10. Other values will generated exceptions",
"operationId": "getOrderById",
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"name": "orderId",
"in": "path",
"description": "ID of pet that needs to be fetched",
"required": true,
"type": "integer",
"maximum": 10.0,
"minimum": 1.0,
"format": "int64"
}
],
"responses": {
"200": {
"description": "successful operation",
"schema": { "$ref": "#/definitions/Order" }
},
"400": { "description": "Invalid ID supplied" },
"404": { "description": "Order not found" }
}
},
"delete": {
"tags": [ "store" ],
"summary": "Delete purchase order by ID",
"description": "For valid response try integer IDs with positive integer value. Negative or non-integer values will generate API errors",
"operationId": "deleteOrder",
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"name": "orderId",
"in": "path",
"description": "ID of the order that needs to be deleted",
"required": true,
"type": "integer",
"minimum": 1.0,
"format": "int64"
}
],
"responses": {
"400": { "description": "Invalid ID supplied" },
"404": { "description": "Order not found" }
}
}
},
"/user": {
"post": {
"tags": [ "user" ],
"summary": "Create user",
"description": "This can only be done by the logged in user.",
"operationId": "createUser",
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"in": "body",
"name": "body",
"description": "Created user object",
"required": true,
"schema": { "$ref": "#/definitions/User" }
}
],
"responses": { "default": { "description": "successful operation" } }
}
},
"/user/createWithArray": {
"post": {
"tags": [ "user" ],
"summary": "Creates list of users with given input array",
"description": "",
"operationId": "createUsersWithArrayInput",
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"in": "body",
"name": "body",
"description": "List of user object",
"required": true,
"schema": {
"type": "array",
"items": { "$ref": "#/definitions/User" }
}
}
],
"responses": { "default": { "description": "successful operation" } }
}
},
"/user/createWithList": {
"post": {
"tags": [ "user" ],
"summary": "Creates list of users with given input array",
"description": "",
"operationId": "createUsersWithListInput",
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"in": "body",
"name": "body",
"description": "List of user object",
"required": true,
"schema": {
"type": "array",
"items": { "$ref": "#/definitions/User" }
}
}
],
"responses": { "default": { "description": "successful operation" } }
}
},
"/user/login": {
"get": {
"tags": [ "user" ],
"summary": "Logs user into the system",
"description": "",
"operationId": "loginUser",
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"name": "username",
"in": "query",
"description": "The user name for login",
"required": true,
"type": "string"
},
{
"name": "password",
"in": "query",
"description": "The password for login in clear text",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "successful operation",
"schema": { "type": "string" },
"headers": {
"X-Rate-Limit": {
"type": "integer",
"format": "int32",
"description": "calls per hour allowed by the user"
},
"X-Expires-After": {
"type": "string",
"format": "date-time",
"description": "date in UTC when token expires"
}
}
},
"400": { "description": "Invalid username/password supplied" }
}
}
},
"/user/logout": {
"get": {
"tags": [ "user" ],
"summary": "Logs out current logged in user session",
"description": "",
"operationId": "logoutUser",
"produces": [ "application/xml", "application/json" ],
"parameters": [ ],
"responses": { "default": { "description": "successful operation" } }
}
},
"/user/{username}": {
"get": {
"tags": [ "user" ],
"summary": "Get user by user name",
"description": "",
"operationId": "getUserByName",
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"name": "username",
"in": "path",
"description": "The name that needs to be fetched. Use user1 for testing. ",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "successful operation",
"schema": { "$ref": "#/definitions/User" }
},
"400": { "description": "Invalid username supplied" },
"404": { "description": "User not found" }
}
},
"put": {
"tags": [ "user" ],
"summary": "Updated user",
"description": "This can only be done by the logged in user.",
"operationId": "updateUser",
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"name": "username",
"in": "path",
"description": "name that need to be updated",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "body",
"description": "Updated user object",
"required": true,
"schema": { "$ref": "#/definitions/User" }
}
],
"responses": {
"400": { "description": "Invalid user supplied" },
"404": { "description": "User not found" }
}
},
"delete": {
"tags": [ "user" ],
"summary": "Delete user",
"description": "This can only be done by the logged in user.",
"operationId": "deleteUser",
"produces": [ "application/xml", "application/json" ],
"parameters": [
{
"name": "username",
"in": "path",
"description": "The name that needs to be deleted",
"required": true,
"type": "string"
}
],
"responses": {
"400": { "description": "Invalid username supplied" },
"404": { "description": "User not found" }
}
}
}
},
"securityDefinitions": {
"api_key": {
"type": "apiKey",
"name": "api_key",
"in": "header"
}
},
"definitions": {
"Order": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"petId": {
"type": "integer",
"format": "int64"
},
"quantity": {
"type": "integer",
"format": "int32"
},
"shipDate": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"description": "Order Status",
"enum": [ "placed", "approved", "delivered" ]
},
"complete": {
"type": "boolean",
"default": false
}
},
"xml": { "name": "Order" }
},
"User": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"username": { "type": "string" },
"firstName": { "type": "string" },
"lastName": { "type": "string" },
"email": { "type": "string" },
"password": { "type": "string" },
"phone": { "type": "string" },
"userStatus": {
"type": "integer",
"format": "int32",
"description": "User Status"
}
},
"xml": { "name": "User" }
},
"Category": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": { "type": "string" }
},
"xml": { "name": "Category" }
},
"Tag": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": { "type": "string" }
},
"xml": { "name": "Tag" }
},
"ApiResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"type": { "type": "string" },
"message": { "type": "string" }
}
},
"Pet": {
"type": "object",
"required": [ "name", "photoUrls" ],
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"category": { "$ref": "#/definitions/Category" },
"name": {
"type": "string",
"example": "doggie"
},
"photoUrls": {
"type": "array",
"xml": {
"name": "photoUrl",
"wrapped": true
},
"items": { "type": "string" }
},
"tags": {
"type": "array",
"xml": {
"name": "tag",
"wrapped": true
},
"items": { "$ref": "#/definitions/Tag" }
},
"status": {
"type": "string",
"description": "pet status in the store",
"enum": [ "available", "pending", "sold" ]
}
},
"xml": { "name": "Pet" }
}
},
"externalDocs": {
"description": "Find out more about Swagger",
"url": "http://swagger.io"
}
}
Data Connection Settings
Now when you type in a new data object name, it will auto-suggest available GET endpoints on the service (type a "/").
Using the /pet/{petId} data object, the showed filter fields would be available, and the display fields will be automatically determined.
Authentication Options
Basic Auth
Standard Authentication (HTTP header with the user and pass encoded in base64) is achieved by providing username and password under credentials.
Windows Authentication
Windows Authentication (Active Directory) has to be enabled in SmartIQ instance.
Access Token (OpenID Connect & SAML)
When SmartIQ is setup to use OpenID Connect authentication, the ResponseType can be configured to retrieve an access_token returned from the IDP. This access_token can be passed to external APIs as authentication as the current user.
OAuth 2.0 Client Credentials
The REST Action and REST Data Connection supports OAuth 2.0 Client Credentials Grant type. This allows the entry of the Client Id, Client Secret and Scope.
The Client Credentials grant is used when applications request an access token to access their own resources, not on behalf of a user. SmartIQ will automatically retrieve the access token from the token endpoint and cache it until expiry.
Each request to the target REST endpoint will include the access token from the cache (or retrieve a new one) in requests as a bearer token header.
Provide the following global configuration in Manage > Settings > REST:
- Default OAuth 2.0 Client Id
- Default OAuth 2.0 Client Secret
- Default OAuth 2.0 Scope
- Default OAuth 2.0 Token Url
The global Token Url can be overridden per datasource in the Connection Attributes or within the security Definitions section of the swagger or the openapi spec.
- In the Connection Attributes the Token Url is specified with the parameter oauthTokenUrl eg:
oauthTokenUrl=https://mytokenurl - In the Definitions section of the swagger or openapi spec the parameter clientCredentials should be set to the token url.
OAuth 2.0 Resource Owner Password Credentials
The REST Action, REST Escalation and REST Data Connection now support OAuth 2.0 Resource Owner Password Credentials Grant type.
Important
Use this function only as a last resort and only if more secure flows are not possible. This flow requires a very high degree of trust in the application, and carries risks which are not present in other flows as the resource owner’s password is exposed to the application.
The Resource Owner Password grant is used when trusted applications requests an access token to access their own resources, not on behalf of a user. SmartIQ will automatically retrieve the access token from the token endpoint and cache it until expiry.
Each request to the target REST endpoint will include the access token from the cache (or retrieve a new one) in requests as a bearer token.
If a username input on an Action of Escalation has a value then resource owner flow will be used.
Provide the following global configuration in Manage > Settings > REST:
- Default OAuth 2.0 Client Id
- Default OAuth 2.0 Client Secret
- Default OAuth 2.0 Scope
- Default OAuth 2.0 Token Url
- Default OAuth 2.0 Username
- Default OAuth 2.0 Password
The global Token Url can be overridden per datasource in the Connection Attributes or within the security Definitions section of the swagger or the openapi spec.
- In the Connection Attributes the Token Url is specified with the parameter oauthTokenUrl eg:
oauthTokenUrl=https://mytokenurl - In the Definitions section of the swagger or openapi spec the parameter password should be set to the token url.
No Credentials Required
Authorization Headers (E.g Custom Header)
Header values can be supplied by the use of a custom header or within the connection string.
When creating a custom filter on a Data Object, names that are surrounded by square brackets are treated as headers and are added to the request.
For example, in Manage Data Object Edit click the Add Custom option and enter a name in brackets eg: [Authorization].
That value will appear in Design as a normal filter field. You can then type "Bearer [q1.AuthorizationToken]" in the filter field in design where [q1.AuthorizationToken], is a reference to a call that creates the actual token.
At runtime SmartIQ will pull out any filter names in square brackets and add them as a header.
The same pattern applies for connection string values. A connection of "schema=...;[Authorization]=Bearer bf17bd59-dc64-44e0-8f96-c175b27a6822" will be sent with a header of "Authorization: Bearer bf17bd59-dc64-44e0-8f96-c175b27a6822".
Connection URL Overrides
The swagger is always exported if it exists in the source environment. The swagger also gets overwritten if it exists in the package being imported.
The base URL for the REST connection can be defined in both an uploaded schema and in the Connection Attributes of the data source. As the schema can be exported between environments, the Connection Attributes definition is used as an environment-specific override of the schema value. If used, the "Export Connection Attributes" option should be left unchecked to avoid overrriding this value and the target value if present in the package being imported.
GET Method
The HTTP GET method is used to "read" (or retrieve) a representation of a resource. In the non-error path, GET returns a representation in XML or JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST).
For this particular scenario, we will use an open API provided by Open Weather Map via Current weather data.
By City Name
This method will return current weather conditions for a particular city, taking one or two parameters: by city name or city name and country code.
api.openweathermap.org/data/2.5/weather?q={city name}
Example:
api.openweathermap.org/data/2.5/weather?q=Canberra
Or
api.openweathermap.org/data/2.5/weather?q={city name},{country code}
Example:
api.openweathermap.org/data/2.5/weather?q=Canberra,au
Sandbox
To use Open Weather Map API, you'll need to create a sandbox and generate an API Key.
Similarly, as defining a JSON Data Source JSON, it is required to specify a JSON Schema in order to map Display fields.
How to create a JSON Schema?
The easiest way to generate a JSON schema is taking a sample JSON response from API and create a schema based on it.
There are a good number of online free tools and Integrated Development Environment (IDE) add-on.
SmartIQ Datasource Configuration
Navigate to SmartIQ Manage > Data Connection.
- Create a local copy of service schema and store it in a location accessible by SmartIQ Web App Server.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json",
"properties": {
"base": {
"default": "stations",
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/base",
"title": "The Base schema.",
"type": "string"
},
"clouds": {
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/clouds",
"properties": {
"all": {
"default": 75,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/clouds/all",
"title": "The All schema.",
"type": "integer"
}
},
"type": "object"
},
"cod": {
"default": 200,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/cod",
"title": "The Cod schema.",
"type": "integer"
},
"coord": {
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/coord",
"properties": {
"lat": {
"default": -35.28,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/coord/lat",
"title": "The Lat schema.",
"type": "number"
},
"lon": {
"default": 149.13,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/coord/lon",
"title": "The Lon schema.",
"type": "number"
}
},
"type": "object"
},
"dt": {
"default": 1490322600,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/dt",
"title": "The Dt schema.",
"type": "integer"
},
"id": {
"default": 2172517,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/id",
"title": "The Id schema.",
"type": "integer"
},
"main": {
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/main",
"properties": {
"humidity": {
"default": 60,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/main/humidity",
"title": "The Humidity schema.",
"type": "integer"
},
"pressure": {
"default": 1021,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/main/pressure",
"title": "The Pressure schema.",
"type": "integer"
},
"temp": {
"default": 21.3,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/main/temp",
"title": "The Temp schema.",
"type": "number"
},
"temp_max": {
"default": 22,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/main/temp_max",
"title": "The Temp_max schema.",
"type": "integer"
},
"temp_min": {
"default": 20,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/main/temp_min",
"title": "The Temp_min schema.",
"type": "integer"
}
},
"type": "object"
},
"name": {
"default": "Canberra",
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/name",
"title": "The Name schema.",
"type": "string"
},
"sys": {
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/sys",
"properties": {
"country": {
"default": "AU",
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/sys/country",
"title": "The Country schema.",
"type": "string"
},
"id": {
"default": 8226,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/sys/id",
"title": "The Id schema.",
"type": "integer"
},
"message": {
"default": 0.0064,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/sys/message",
"title": "The Message schema.",
"type": "number"
},
"sunrise": {
"default": 1490299782,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/sys/sunrise",
"title": "The Sunrise schema.",
"type": "integer"
},
"sunset": {
"default": 1490342954,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/sys/sunset",
"title": "The Sunset schema.",
"type": "integer"
},
"type": {
"default": 1,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/sys/type",
"title": "The Type schema.",
"type": "integer"
}
},
"type": "object"
},
"visibility": {
"default": 10000,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/visibility",
"title": "The Visibility schema.",
"type": "integer"
},
"weather": {
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/weather",
"items": {
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/weather/0",
"properties": {
"description": {
"default": "broken clouds",
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/weather/0/description",
"title": "The Description schema.",
"type": "string"
},
"icon": {
"default": "04d",
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/weather/0/icon",
"title": "The Icon schema.",
"type": "string"
},
"id": {
"default": 803,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/weather/0/id",
"title": "The Id schema.",
"type": "integer"
},
"main": {
"default": "Clouds",
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/weather/0/main",
"title": "The Main schema.",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"wind": {
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/wind",
"properties": {
"deg": {
"default": 110,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/wind/deg",
"title": "The Deg schema.",
"type": "integer"
},
"speed": {
"default": 4.1,
"description": "An explanation about the purpose of this instance.",
"id": "http://api.openweathermap.org/data/2.5/weather/root.json/wind/speed",
"title": "The Speed schema.",
"type": "number"
}
},
"type": "object"
}
},
"type": "object"
}
- Change Data Connection Name to REST GET Datasource.
- Select Connection Type as REST.
- Connection String requires two values:
- baseUrl = the first section of the service URL (eg baseUrl=http://server/)
- schema = the JSON schema definition of the result from the API call (schema=c:\temp\user.json)
baseurl=http://api.openweathermap.org;schema=C:\inetpub\wwwroot\SmartIQ\datasource\weatherService.schema.json
- Click Test Connection to validate that SmartIQ can establish a connection with JSON and Schema files.
- Click Save.
Good practice
It is recommended to enable "Allow Connection Export" as it will make the data source part of a project definition allowing to import it in a different environment.
After saving REST Data Connection in Manage, click the Data Objects button. This will bring a new window with all available Data Objects for this particular Data Connection.
The data object name is the rest of the API URL (e.g. api/{username}/invoice?id={invoiceid}). Key fields are extracted from the URL, template fields and display fields are read from the schema file (same as the JSON Data Connection JSON)
-
Click on New Data Object. Provide the following information:
Object Type: Method
Data Object Name / Definition: /data/2.5/weather?q={cityAndCode}&appid=yourAPIKey&units=metric
Display Name: CurrentByCity -
Add all filter fields clicking on Add All >> button.
-
Click the Save button.
http://api.openweathermap.org/data/2.5/weather?q={cityAndCode}&appid=yourAPIKey&units=metric
Simple Test
A straightforward way to test you have the correct endpoint, copy/paste the complete URL into a new tab in your browser, you should get a JSON response.
{
"coord": {
"lon": 149.13,
"lat": -35.28
},
"weather": [{
"id": 801,
"main": "Clouds",
"description": "few clouds",
"icon": "02d"
}],
"base": "stations",
"main": {
"temp": 11,
"pressure": 1020,
"humidity": 53,
"temp_min": 11,
"temp_max": 11
},
"visibility": 10000,
"wind": {
"speed": 1.5,
"deg": 310
},
"clouds": {
"all": 20
},
"dt": 1503363600,
"sys": {
"type": 1,
"id": 8226,
"message": 0.0115,
"country": "AU",
"sunrise": 1503347775,
"sunset": 1503387420
},
"id": 2172517,
"name": "Canberra",
"cod": 200
}
Post Method
The POST verb is most-often utilised to "create" new resources but also to retrieve data based on some parameters passed as in the body request. On successful, return HTTP status 201, returning a Location header with a link to the newly-created resource with the 201 HTTP status.
For this particular scenario, we will use Text Analytics API provided by Microsoft Azure Cognitive Services. The Text Analytics API is a suite of text analytics web services built with Azure Machine Learning. The API can be used to analyse unstructured text for tasks such as sentiment analysis, key phrase extraction and language detection. No training data is needed to use this API.
The Azure Text Analytics Quick Start provides all required information to configure this service in your Microsft Azure subscription.
Sandbox
To use Microsoft Azure Text Analytics, you'll need a Microsoft Azure account. (30 day trial with $200 free credit is available)
Note
Microsoft Azure Text Analytics provides a Swagger Definition that could be downloaded and used within SmartIQ containing request and response definitions for all methods (no need to create n number of Data Sources) however, in this example we will use JSON Schema to explain the difference between request and response.
POST method requires an extra parameter in the connection string pointing to the JSON Schema of the response.
- baseUrl = the first section of the service URL.
- schema = the JSON schema definition of the result from the API call.
- postSchema = the JSON schema definition of the request to the API.
- Create a new Data Connection using following information:
schema=C:\inetpub\wwwroot\SmartIQ\Datasource\TextAnalyticsLanguage.schema.json;postschema=C:\inetpub\wwwroot\SmartIQ\Datasource\TextAnalyticsLanguage.postschema.json;baseurl=https://westus.api.cognitive.microsoft.com
{
"type": "object",
"properties": {
"documents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Unique document identifier.",
"type": "string"
},
"detectedLanguages": {
"description": "A list of extracted languages.",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"description": "Long name of a detected language (e.g. English, French).",
"type": "string"
},
"iso6391Name": {
"description": "A two letter representation of the detected language according to the ISO 639-1 standard (e.g. en, fr).",
"type": "string"
},
"score": {
"format": "double",
"description": "A confidence score between 0 and 1. Scores close to 1 indicate 100% certainty that the identified language is true.",
"type": "number"
}
}
}
}
}
}
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Input document unique identifier the error refers to.",
"type": "string"
},
"message": {
"description": "Error message.",
"type": "string"
}
}
}
}
}
}
{
"type": "object",
"properties": {
"documents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Unique, non-empty document identifier.",
"type": "string"
},
"text": {
"type": "string"
}
}
}
}
}
}
- Create a new Data Object, where:
Object Type: Method
Data Object Name / Definition: /text/analytics/v2.0/languages
Display Name: Languages
- Click the Save button.
Data Object is created with filter and display fields specified in schemas, however, for this particular example, an extra header for API Key requires to be defined.
- Click on Add Custom.
- Type: [Ocp-Apim-Subscription-Key] and click on Add.
An extra filter field will be added into this Data Object. Later Designer has to pass in the API Key to this custom header.
Array Data Filter
A REST data connector can use a repeat data filter to configure a JSON array.
- In your Data Object, add the following available fields as filter fields
- documents[]
- documents[].id
- documents[].text
- In Design, create a repeating section and within the repeating section, add two text fields called Id and Text.
- Below the repeating section, add your Datasource and select the Data Object.
- Add a repeat data filter
- Filter Field: $.documents[]
- Select Type: Repeat
- Repeat Source: Your repeating section
- We can now configure the array object property
- Select the repeat filter field created in the previous step
- Change Filter Field to $.documents[].id
- For comparison, select Equals
- Change Type to Parent Question
- Select the Id text field which is in the repeating section
- Repeat step 5 for the $documents[].text field
Your data filter tab should look like this:
Notice that the $.documents[].id and $.documents[].text fields are indented below the $.documents[] filter. This means that it will create a new object under each row of a repeating section. With 2 rows in a repeating section, your POST data will look something like this:
{
"documents":[
{
"id": "1",
"text": "First row"
},
{
"id": "2",
"text": "Second row"
}
]
}
Troubleshooting
An option "Enable advanced results display in Troubleshooting Mode" exists in the configuration for any REST data connector in Manage to allow the request and response for that data connector to be displayed in troubleshooting mode.
The option needs to be selected AND troubleshooting mode needs to be enabled for the project for this to appear.
Legacy REST Date Handling
In versions prior to v11, Infiniti always handled any data from a JSON or REST data source that looked like a date as a date, regardless of the underlying data type. This sometimes caused issues where values that were intended to remain as strings were being interpreted incorrectly.
Infiniti v11 introduces a new way of handling dates, where the data type must be defined as 'date-time' before treating a value as a date. Strings will be treated just as strings, reducing the issues associated with incorrectly applying date formatting. Further, if you wish to treat a string as a date you will need to apply a format to it, e.g. 'yyyy-MM-ddThh:mm:ss.fffffff'.
This feature also provides a backwards compatibility mode through a new connection string attribute - 'datemode=v10'. This attribute is automatically added to existing JSON and REST data sources for environments upgraded from earlier versions, to reduce the likelihood of introducing upgrade related issues. Any new data source added will not include this attribute automatically, so to apply simply add 'datemode=v10' into the relevant data source connection string in Manage.
Updated over 2 years ago