HTTP::Abstract

The HTTP :: Abstract device adapter allows data to be submitted by any HTTP enabled device or platform. The values supplied by the device are sent using standard HTTP GET/POST parameter name/ value pairs or via POST requests using JSON data encoding.

HTTP Request Types (non-JSON encoding)

A device will create a GET or POST request using the message’s “Code” value as the “code” parameter value. The values provided by the device must correspond to the data type as defined in the device profile message definition. Submitting data via a POST request will require the request have its “Content-Type” header value set to application/x-www-form-urlencoded.

Required and Predefined Request Parameter Names

The following list of parameter names identify the minimum required parameters and some optional predefined parameters for each message submitted via this interface.

code

target

time

latitude and longitude

Message Fields Any value the device wishes to send to the server must appear as a field in the message definition. None of the field ‘code’ values must have the same value as the parameter names identified in the previous section.

The data value supplied for each parameter must correspond to the data type specified in the message field definition.

Here’s an example message definition screen shot where the message definition contains one field, named ‘pct_full’, being supplied by the device. That field is a floating point number field.

The GET or POST request must supply a parameter with a name of ‘pct_full’ and a value to be processed for that field. Here’s an example of a Unix ‘curl’ command that submits the ‘pct_full’ field value via a ‘pct_full’ parameter in the request.

#!/bin/bash
Connecting a Device
export LAT=37.795227
export LNG=-122.398828
export URL=http://com99.sl.fusionconnect.io:49080
export DATE_STR=`date -u '+%Y-%m-%dT%TZ'`
export MSG_PARAMS="code=message_code_value&target=unique_device_id&
time=$DATE_STR&latitude=$LAT&longitude=$LNG&pct_full=0.7450"

# Send via POST request
curl -v -X POST -H "Content-Type:application/
x-www-form-urlencoded;charset=UTF-8" -d "$MSG_PARAMS" $URL

# Send via GET request
curl -v -G -d "$MSG_PARAMS" $URL

The client device may use any functional HTTP client software to submit data via this “HTTP :: Abstract” interface.

GET/POST (non-JSON) Response Contents

The response to the client submitting a message will fall into two general categories:

Processing JSON Encoded Data

JSON encoded data is sent as mime type “application/json” data via a POST request. The “HTTP :: Abstract” device adapter will process JSON requests when submitted using the “/json” URI.

http://com99.sl.fusionconnect.io:49080/json Please obtain the hostname and port number that is appropriate for your application from your application support representative.

See JSON Encoded Data for more information.

POST Request Responses for JSON Encoded Data

When JSON encoding is used to submit data to the server using the “HTTP :: Abstract” device adapter, the client will receive a JSON response payload in the request response body showing whether the message was processed successfully and an optional message if an error occurred.

JSON Response Examples

No errors: {"success": true}

Missing target field: {"success":false,"message":"No (device code) \u0027target\u0027 value was supplied"}

Server-to-Device Messaging (Directives)

This device adapter supports the sending of messages to the device via JSON encoded data contained in the response body. The “Content-Type” of the response will be set to “application/json”.

The device is responsible for checking for available directive messages by periodically submitting directive requests to the server. If a directive message is available for the requesting device, the JSON response will have a “success” value of (boolean) true and a “count” field value greater than zero. The other JSON message fields will be the values supplied from the directive message as defined later in this section.

If the “count” value is greater than one, the device will need to submit additional directive requests to the server to retrieve each additional directive message that is available for the device.

When the “count” field value is zero, there are no directive messages available for the device.

Directive Requests

The same base hostname and port is used for a directive request from the device, except a “/directive” URI value is appended to the base request.

POST (JSON) =>http://com99.sl.fusionconnect.io:49080/json/directive

Obtain the hostname and port number that is appropriate for your application from your application support representative.

Directive Response JSON Data

success

message

count

target

code

time

location

values

Example Directive JSON Data

Here is an example directive (outbound) message definition. The “Location” field has a code value “location_” to have the geo location value provided via the top level “location” field.

Here’s an example of this directive (outbound) JSON message contents:

{
"time":"2015-12-11T22:36:38Z",
"target":"ABC123",
"code":"cmd1",
"location":{"latitude":37.399489,"longitude":-122.055252},
"count":1,
"success":true,
"values":{
"date_1":"2015-12-11T22:36:10Z",
"number_1":2.34,
"text_1":"Test 1",
"integer_1":1,
"boolean_1":true}
}
Parent page: Abstract Adapters