MTConnect REST API and WebSockets

Overview

MTConnect has supported the normative REST API since its inception in 2008. REST was chosen because it offered a simple way to interact with the Agent and provide a lightweight store-and-forward service that would allow for high-speed data transfer without any server sessi on-related overhead. There is more information in the MTConnnect model documentation: MTConnect Fundementals.

REST APIs

The MTConnect agent is capable of producing a Swagger document providing all the information about the implemented protocol in the Agent: mtconnect.json. The to access the document from any Agent post 2.0 you can use the following rest interface:

• http://<ip>:<port>/swagger[?pretty=true]
  • pretty formats the json document so it is easier to read
    • Default: false
  • Example: https://demo.mtconnect.org/swagger?pretty=true

MTConnect – REST API

MTConnect APIs

Request	Description
/probe	Returns an MTConnect Device model document describing all the devices represented by agent
/current	Returns an MTConnect Streams document providing a snapshot of the observations
/sample	Returns an MTConnect Streams document of time series changes to the observations
/asset	Returns an MTConnect Assets document that returns a set of MTConnect Asset document types

For more information, see the current MTConnect Swagger Documentation

Swagger REST API Documentation

WebSocket API

For information on WebSockets, please see WebSocket – Wikipedia

The WebSocket API uses the same parameters as the REST API; the only addition is the required id to determine which response is related to which request. The id also allows one to cancel the request when it is streaming.

For WebSockets, you need to connect to the server, upgrade the HTTP connection to WebSockets, and then send requests:

{
  "id": "ABC",
  "request": "probe"
}

The id and request are required.

You can use the format optional key to return either JSON or XML. XML is returned by default.

{
  "id": "ABC",
  "request": "probe",
  "format": "json"
}

Or

{
  "id": "ABC",
  "request": "probe",
  "format": "xml"
}

All the properties except request and id are the same as the properties you get from the swagger interface. Make a request to /swagger from the agent to find all the possible properties.

   https://demo.mtconnect.org/swagger

When an interval is given for sample or current, they will publish at the given interval in milliseconds. A request of cancel will stop a request.

For example, the following does a probe with results in json and then requests a current that returns an xml document. From the current, we determine the next sequence is 1632321 and ask it to begin streaming with changes every 1 second (1000 ms). The next request gets a current every 5 seconds and then cancels the sample with id number 3.

{"id": 1,"request": "probe", "format": "json"}
{"id": 2,"request": "current"}
{"id": 3, "request": "sample", "interval": 1000, "format": "json", "from": 1632321}
{"id": 4, "request": "current", "interval": 5000 }
{"id": 3, "request": "cancel"}

The results are chunked according to the WebSockets specification as individual messages.