REST Protocol Package

An agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. MUST provide a REST API API supporting HTTP version 1.0 or greater. This interface MUST support HTTP (RFC7230) and use URIs (RFC3986) to identify specific information requested from an agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. .

The REST API adheres to the architectural principles of a stateless service to retrieve information associated with pieces of equipment. Additionally, the API is read-only and does not produce any side effects on the agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. or the equipment. In REST state management, the client is responsible for recovery in case of an error or loss of connection.

HTTP Request

The HTTP uses Uniform Resource Identifiers (URI) as outlined in IETF RFC 3986 as the request-target. IETF RFC 7230 specifies the http URI scheme for the request-target as follows:

protocol: The protocol used for the request. Must be http or https.
authority: The network domain or address of the agent with an optional port.
path: A Hierarchical Identifier following a slash (/) and before the optional question-mark (?). The path separates segments by a slash (/).
query: The portion of the HTTP request following the question-mark (?). The query portion of the HTTP request is composed of key-value pairs, <key>=<value> separated by an ampersand (&).

`path` Portion of an HTTP Request

The path portion of the request-target has the following segments:

device-name or uuid: optional name or uuid of the Device
request: request, must be one of the following: (also see Section Operations for Agent)
- REST Protocol::probe
- REST Protocol::current
- REST Protocol::sample
- REST Protocol::asset or assets
  - REST Protocol::asset request has additional optional segment <asset ids>

If name or uuid segement are not specified in the HTTP Requestrequest message from a client to a server includes, within the first line of that message, the method to be applied to the resource, the identifier of the resource, and the protocol version in use. IETF:RFC-2616 > Note: In MTConnect Standard, a request issued by a client to an agent requesting information defined in the HTTP Request Line. , an agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. MUST return information for all pieces of equipment. The following sections will

Examples:

http://localhost:5000/my_device/probe
The request only provides information about my_device.
http://localhost:5000/probe
The request provides information for all devices.

The following section specifies the details for each request.

MTConnect REST API

An agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. MUST support probe requestsrequest to an agent to produce an MTConnectDevices Response Document containing the Device Information Model., current requestsrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a snapshot of the latest observations at the moment of the request or at a given sequence number., sample requestsrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a set of timestamped observations made by Components., and asset requestsHTTP Request to the agent regarding Assets..

See the operations of the Agent for details regarding the requestscommunications method where a client transmits a message to an agent. That message instructs the agent to respond with specific information..

HTTP Errors

When an agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. receives an HTTP Requestrequest message from a client to a server includes, within the first line of that message, the method to be applied to the resource, the identifier of the resource, and the protocol version in use. IETF:RFC-2616 > Note: In MTConnect Standard, a request issued by a client to an agent requesting information defined in the HTTP Request Line. that is incorrectly formatted or is not supported by the agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. , the agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. MUST publish an HTTP Error Messageresponse provided by an agent indicating that an HTTP Request is incorrectly formatted or identifies that the requested data is not available from the agent. IETF:RFC-2616 which includes a specific status code from the tables above indicating that the requestcommunications method where a client transmits a message to an agent. That message instructs the agent to respond with specific information. could not be handled by the agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. .

Also, if the agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. experiences an internal error and is unable to provide the requested response documentelectronic document published by an MTConnect Agent in response to a probe request, current request, sample request or asset request., it MUST publish an HTTP Error Messageresponse provided by an agent indicating that an HTTP Request is incorrectly formatted or identifies that the requested data is not available from the agent. IETF:RFC-2616 that includes a specific status code from the table above.

Streaming Data

HTTP data streamingmethod for an agent to provide a continuous stream of information in response to a single request from a client. is a method for an agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. to provide a continuous stream of observationsobserved value of a property at a point in time. in response to a single requestcommunications method where a client transmits a message to an agent. That message instructs the agent to respond with specific information. using a publish and subscribeasynchronous communication method in which messages are exchanged between applications without knowing the identity of the sender or recipient. > Note: In the MTConnect Standard, a communications messaging pattern that may be used to publish streaming data from an agent. communication pattern.

When an HTTP Requestrequest message from a client to a server includes, within the first line of that message, the method to be applied to the resource, the identifier of the resource, and the protocol version in use. IETF:RFC-2616 > Note: In MTConnect Standard, a request issued by a client to an agent requesting information defined in the HTTP Request Line. includes an interval parameter, an agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. MUST provide data with a minimum delay in milliseconds between the end of one data transmission and the beginning of the next. A value of zero (0) for the interval parameter indicates that the agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. should deliver data at the highest rate possible and is only relevant for sample requestsrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a set of timestamped observations made by Components. .

The format of the response MUST use an x-multipart-replace encoded message with each section separated by MIME boundaries. Each section MUST contain an entire MTConnectStreams Response Documentresponse document published by an MTConnect Agent in response to a current request or a sample request..

When streaming for a current requestrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a snapshot of the latest observations at the moment of the request or at a given sequence number., the agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. produces an MTConnectStreams Response Documentresponse document published by an MTConnect Agent in response to a current request or a sample request. with the most current observationsobserved value of a property at a point in time. every interval milliseconds.

When streaming for a sample requestrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a set of timestamped observations made by Components., if there are no available observationsobserved value of a property at a point in time. after the interval time elapsed, the agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. MUST wait for either the heartbeat time to elapse or an observationobserved value of a property at a point in time. arrives. If the heartbeat time elapses and no observationsobserved value of a property at a point in time. arrive, then an empty MTConnectStreams Response Documentresponse document published by an MTConnect Agent in response to a current request or a sample request. MUST be sent.

Note: For more information on MIME, see IETF RFC 1521 and RFC 822.

An example of the format for an HTTP Requestrequest message from a client to a server includes, within the first line of that message, the method to be applied to the resource, the identifier of the resource, and the protocol version in use. IETF:RFC-2616 > Note: In MTConnect Standard, a request issued by a client to an agent requesting information defined in the HTTP Request Line. that includes an interval parameter is:

http://localhost:5000/sample?interval=1000

HTTP Response Header:

HTTP/1.1 200 OK
Connection: close
Date: Sat, 13 Mar 2010 08:33:37 UTC
Status: 200 OK
Content-Disposition: inline
X-Runtime: 144ms
Content-Type: multipart/x-mixed-replace;boundary=
a8e12eced4fb871ac096a99bf9728425
Transfer-Encoding: chunked

Lines 1-9 in http-response-header represent a standard header for a MIME multipart/x-mixed-replace message. The boundary is a separator for each section of the stream. Lines 7-8 indicate this is a multipart MIME message and the boundary between sections.

With streaming protocols, the Content-length MUST be omitted and Transfer-Encoding MUST be set to chunked (line 9). See IETF RFC 7230 for a full description of the HTTP protocol and chunked encoding.

--a8e12eced4fb871ac096a99bf9728425
Content-type: text/xml
Content-length: 887

<?xml version="1.0" ecoding="UTF-8"?>
<MTConnectStreams ...>...

Each section of the document begins with a boundary preceded by two hyphens (--). The Content-type and Content-length header fields MUST be provided for each section and MUST be followed by <CR><LF><CR><LF> (ASCII code for <CR> is 13 and <LF> 10) before the XML document. The header and the <CR><LF><CR><LF> MUST NOT be included in the computation of the content length.

An agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. MUST continue to stream results until the client closes the connection. The agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. MUST NOT stop streaming for any reason other than the following:

agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. process stops
The client application stops receiving data

Heartbeat

When streaming dataobservations published by a piece of equipment defined by the equipment metadata. is requested from a sample requestrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a set of timestamped observations made by Components., an agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. MUST support a heartbeatfunction that indicates to a client that the communications connection to an agent is still viable during times when there is no new data available to report often referred to as a “keep alive” message. to indicate to a client application that the HTTP connection is still viable during times when there is no new data available to be published. The heartbeatfunction that indicates to a client that the communications connection to an agent is still viable during times when there is no new data available to report often referred to as a “keep alive” message. is indicated by an agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. by sending an MTConnect response documentelectronic document published by an MTConnect Agent in response to a probe request, current request, sample request or asset request. with an empty Steams entity (See Observation Information Model for more details on Streams) to the client software application.

The heartbeatfunction that indicates to a client that the communications connection to an agent is still viable during times when there is no new data available to report often referred to as a “keep alive” message. MUST occur on a periodic basis given by the optional heartbeat query parameter and MUST default to 10 seconds. An agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. MUST maintain a separate heartbeatfunction that indicates to a client that the communications connection to an agent is still viable during times when there is no new data available to report often referred to as a “keep alive” message. for each client application for which the agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. is responding to a data streamingmethod for an agent to provide a continuous stream of information in response to a single request from a client. requestcommunications method where a client transmits a message to an agent. That message instructs the agent to respond with specific information..

An agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. MUST begin calculating the interval for the time-period of the heartbeatfunction that indicates to a client that the communications connection to an agent is still viable during times when there is no new data available to report often referred to as a “keep alive” message. for each client application immediately after a response documentelectronic document published by an MTConnect Agent in response to a probe request, current request, sample request or asset request. is published to that specific client application.

The heartbeatfunction that indicates to a client that the communications connection to an agent is still viable during times when there is no new data available to report often referred to as a “keep alive” message. remains in effect for each client software application until the data streamingmethod for an agent to provide a continuous stream of information in response to a single request from a client. requestcommunications method where a client transmits a message to an agent. That message instructs the agent to respond with specific information. is terminated by either the agentsoftware that collects data published from one or more piece(s) of equipment, organizes that data in a structured manner, and responds to requests for data from client software systems by providing a structured response in the form of a response document that is constructed using the semantic data model of a Standard. or the client application.

References

A Component MAY include a set of Reference entities of the following types that MAY alter the content of the MTConnectStreams Response Documentsresponse document published by an MTConnect Agent in response to a current request or a sample request. published in response to a current requestrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a snapshot of the latest observations at the moment of the request or at a given sequence number. or a sample requestrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a set of timestamped observations made by Components. as specified:

A Componentengineered system part of a Device composed of zero or more Components reference (ComponentRef) modifies the set of Observationsobservation that provides telemetry data for a DataItem., limited by a path query parameter of a current requestrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a snapshot of the latest observations at the moment of the request or at a given sequence number. or sample requestrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a set of timestamped observations made by Components., to include the Observationsobservation that provides telemetry data for a DataItem. associated with the entity whose value for its id attribute matches the value provided for the idRef attribute of the ComponentRef element. Additionally, Observationsobservation that provides telemetry data for a DataItem. defined for any lower levelnested element that is below a higher level element. entity(s) associated with the identified entities MUST also be returned. The result is equivalent to appending //[@id=<"idRef">] to the path query parameters of the current requestrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a snapshot of the latest observations at the moment of the request or at a given sequence number. or sample requestrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a set of timestamped observations made by Components.. See Agent for more details on path queries.
A DataItemobservable observed by a Component that may make Observations reference (DataItemRef) modifies the set of resulting Observationsobservation that provides telemetry data for a DataItem., limited by a path query parameter of a current requestrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a snapshot of the latest observations at the moment of the request or at a given sequence number. or sample requestrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a set of timestamped observations made by Components., to include the Observationsobservation that provides telemetry data for a DataItem. whose value for its id attribute matches the value provided for the idRef attribute of the DataItemRef element. The result is equivalent to appending //[@id=<"idRef">] to the path query parameters of the current requestrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a snapshot of the latest observations at the moment of the request or at a given sequence number. or sample requestrequest to an agent to produce an MTConnectStreams Response Document containing the Observation Information Model for a set of timestamped observations made by Components.. See Agent for more details on path queries.

Agent