How to Connect to a JSON HTTP or REST Machine Data Source

The JSON HTTP device type is a powerful tool that enables us to gather data from API endpoints, normalize that data into our common data model, and push the data to our cloud to represent the state and behavior of a machine.

Some machine vendors have API endpoints that expose machine data in a format known as JavaScript Object Notation or JSON. This enables us to capture data from these machines. Additionally, this enables a more rapid path to custom connector creation by developing API endpoints that expose the current state of the machine which can be regularly polled.

Getting Started

When adding a new machine that has an API endpoint that makes data available in a JSON format via HTTP, choose the JSON HTTP option from the Data Collection Method dropdown menu.

Type the URL of the endpoint into the Connection Address field. It will look something like http://192.168.100.132. The IP address will be unique to your piece of equipment or API endpoint. Some endpoints are located at a deeper directory structure than the root. If the path to the endpoint is the same for all data points, you can include that in the URL like so: http://192.168.100.132/path/to/endpoint. If some data points have different paths, only include the top level portion of the URL and see below for more.

In the Configure your adapter section, you will need to write an Adapter Script that informs our software about the shape of the data, how it should be translated into the common data format, and then prepared for output as data-items.

This document focuses on the aspects of the Adapter Script which are specific to the JSON HTTP source type. See the Configuration Script Overview-V2 for an overall look at the Adapter Scripts.

Attributes

props

The props attribute is where all data is defined. There are two syntaxes for defining a prop.

The shorthand syntax is for more applications and assumes that the connector will only be communicating with a single API endpoint or route. This route is specified in the Connection Address field of the Connectivity Method form. In this case, props are defined as a dictionary of keys and their respective paths.

# shorthand example
props: 
  key: path.to.attribute

The longhand syntax is for more complex applications where more than one API endpoint or route is used across all of the props. This route is a concatenation of the Connection Address field and the route property specified for each prop.

# longhand example
props: 
  key:
    path: path.to.attribute
    route: /some/api/route

For more information on the path syntax, see the section covering JSON Path Syntax below.

data-items, variables, and conditions, etc

For information on the common attributes that are available within all Adapter Scripts, please review their respective documentation.

Optional Attributes

The following attributes are applied at the top level of the Adapter Script and are not required.

scan-interval

Default value is 1. This is the number of seconds that the connector will wait between each polling loop.

version: 2 
scan-interval: 3
props:
  test: a.b
data-items:
  - test

insecure

Default value is false. This can be used to communicate with HTTPS endpoints when the certificate cannot be validated. This might apply if the server has a self-signed certificate.

version: 2 
insecure: true
props:
  test: a.b
data-items:
  - test

Extended JSON Path Syntax

Introduction

The Extended JSON Path Syntax is a specialized string format designed for identifying and navigating to a specific property within complex JSON objects, including those with nested objects and arrays of objects.

Syntax Overview

• Regular Path String
  • Example: machine.system.state navigates to the state property nested inside system and machine.
• Extended Find Notation
  • Example: machines[id=102].location searches within machines for an object where the property id equals 102, then navigates to its location property.

The examples below focus on the props section of the config.

Basic Path

Example Config

props: 
  test: a.b.c

Assumed Response

{ 
  "a": { 
    "b": { 
      "c": "test" 
    } 
  } 
}

Description: Here, the property test uses the basic path a.b.c to navigate and extract the value "test" from the JSON response.

Dedicated Route with Path

Example Config

props: 
  test-dedicated-route: 
    path: d.e.f 
    route: /other-route

Assumed Response to /other-route

{ 
  "d": { 
    "e": { 
      "f": "test-dedicated-route" 
    } 
  }
}

Description: The property test-dedicated-route uses the dedicated path d.e.f to extract the value from the JSON response from the /other-route endpoint.

Search within Array

Example Config

props: 
  test-search-array: g.h[i=j].k

Assumed Response

{ 
  "g": { 
    "h": [
      { 
        "i": "j", 
        "k": "test-search-array" 
      }
    ]
  } 
}

Description: This example searches the array in the path g.h for an object where i is equal to j and then extracts the value of the k property from that object.

Search within Array with a Dedicated Route

Example Config

props: 
  test-search-array-root: 
    path: "[l=m].n[o=p].q" 
    route: /array

Assumed Response to /array

[ 
  { 
    "l": "m", 
    "n": [ 
      { 
        "o": "p", 
        "q": "test-search-array-root" 
      } 
    ] 
  } 
]

Description: This searches the root array for an object where l equals m. Then, it navigates to its nested array n to find an object where o equals p and extracts the value of the q property.

Extracting using an Array Index with a Dedicated Route

Example Config

props: 
  test-index-array: 
    path: 0.r.s 
    route: /array

Assumed Response to /array

[
  { 
    "r": { 
      "s": "test-index-array" 
    } 
  } 
]

Description: This example navigates to the first object (index 0) of the root array and then extracts the value of the s property located under r.