Messages Resource

DELETE /messages

Delete all messages published on the account, eventually in a given time range. The time range is defined by year and week number. The first day of week is SUNDAY.

If topic is set, only messages belonging to this topic and sub-topics will be erased

If purge flag is set to true, time range is ignored and all messages are deleted.

The time range is from startYear+startWeek (included) to endYear+endWeek (included).
If startWeek is omitted (set to -1), all messages older than endYear+endWeek (included) will be deleted.
If startYear+startWeek is set then endYear+endWeek is mandatory.
If startYear+startWeek and endYear+endWeek are omitted (set to -1), all messages belonging to this account will be deleted.

Warning: If purge flag is true, all messages will be deleted as well as TopicsByAccount, TopicsByAssets and AssetsByAccount. Purge should not be true if a date is set.

Examples of topics:

Topic Resulting operation
edcguest/Device_Id_01/car/route/two Deletes all messages for this topic (only asset Device_Id_01 is concerned)
edcguest/Device_Id_01/tram/# Deletes all messages for asset Device_Id_01 under tram topic (including all subtopics)
edcguest/+/car/route/one Deletes all messages for all assets under car/route/one topic and deletes topic car/route/one
edcguest/+/car/# Deletes all messages for all assets under car and all subtopics and deletes topic car and all subtopics
edcguest/Device_Id_01/# Deletes all messages for asset Device_Id_01 and delete asset Device_Id_01
edcguest/+/# Delete all messages published on the account and reset account to the initial state without assets and topics (same function as messages/purge.xml)

Remember to use URL-encoding for the following symbols:

Character URL encoding
/ %2F
+ %2B
# %23

Example of query in CURL:
curl --user 'username:password' -X DELETE -k https://api-sandbox.everyware-cloud.com/v2/messages.xml?startYear=2012&startWeek=48&endYear=2013&endWeek=9"
(delete all messages from 11/26/2012 to 3/3/2013)

Request Parameters
name type description default constraints
endWeek query number of the end week in endYear to be deleted. The parameter is expressed as an int. -1 required
endYear query The parameter is expressed as an int. -1 required
purge query Warning: If set to true, all messages will be deleted as well as TopicsByAccount, TopicsByAssets and AssetsByAccount. false required
startWeek query number of the start week in startYear to be deleted. The parameter is expressed as an int. -1 required
startYear query The parameter is expressed as an int. -1 required
topic query see examples above.    

Example

Request
DELETE /messages
Content-Type: */*

                
...
Response
HTTP/1.1 204 No Content

GET /messages

Returns the list of all the Messages published under the account of the currently connected user. The startDate and endDate query parameters determine the time range for the messages returned; the timestamp of the returned messages will be in the interval between startDate and endDate. For each returned message, the topic string and timestamp of its last received message will be returned.

If the flag MessagesResult.limitExceeded is set, the maximum number of entries to be returned has been reached, more data exist and can be read by moving the offset forward in a new request.

If the parameter "sort" is set to "asc", messages are returned oldest first. 

 Example to get all messages:
 // First get the total count of messages
 String apiPath = "messages/count.xml";
 WebResource apisWeb = client.resource(API_URL).path(apiPath);
 CountResult countResult = apisWeb.get(CountResult.class);
 
 // Then paginate to get all messages
 long MSG_COUNT = countResult.getCount();
 apiPath = "messages.xml";
 apisWeb = client.resource(API_URL).path(apiPath);
 
 for (int offset = 0; offset < MSG_COUNT; offset += limit) {
 // set limit and offset as queryParam
 // if the "limit" queryParam is not initialized, limit default value = 50
 // if the "offset" queryParam is not initialized, offset default value = 0
 apisWeb = apisWeb.queryParam("limit", "" + limit);
 if (offset > 0)
 apisWeb = apisWeb.queryParam("offset", "" + offset);
 
 MessagesResult result = apisWeb.get(MessagesResult.class);
 }
 
 // To get all messages of a given topic
 apiPath = "messages/searchByTopic.xml";
 apisWeb = client.resource(API_URL).path(apiPath);
 apisWeb = apisWeb.queryParam("topic", topic);
 
 MessagesResult result;
 int offset = 0;
 do {
 apisWeb = apisWeb.queryParam("limit", "" + limit);
 if (offset > 0)
 apisWeb = apisWeb.queryParam("offset", "" + offset);
 result = apisWeb.get(MessagesResult.class);
 offset += limit;
 } while (result.isLimitExceeded()):

Example of query in CURL :
curl --user 'clientId:client password' -k https://api-sandbox.everyware-cloud.com/v2/messages.xml?startDate=2013-02-19T14:11:00&endDate=2013-02-19T14:12:00" | xmllint --format -

Request Parameters
name type description default constraints
endDate query End date of the date range requested. The parameter is expressed as a long counting the number of milliseconds since January 1, 1970, 00:00:00 GMT. If not specified it means current time. Alternatively, the date can be expressed as a string following the ISO 8601 format. 0  
fetch query Specifies the amount of information requested. Allowed values are: meta, metrics, all. "meta" returns only the topic and received on information; "metrics" returns "meta" plus all the metrics included in the message; "all" returns the whole message including its binary payload. metrics  
limit query Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. 50 required
offset query Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. 0 required
sort query specify the timestamp sort order for messages : "asc" return messages in ascending order (oldest first), "desc" or not set, messages are returned newest first desc  
startDate query Start date of the date range requested. The parameter is expressed as a long counting the number of milliseconds since January 1, 1970, 00:00:00 GMT. If not specified it means no start date. Alternatively, the date can be expressed as a string following the ISO 8601 format. 0  
Response Body
media type data type description
application/json MessagesResult (JSON) The list of requested Messages.
application/xml messagesResult (XML)

Example

Request
GET /messages
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "limitExceeded" : true,
  "message" : [ {
    "topic" : "...",
    "receivedOn" : 12345,
    "payload" : {
      "sentOn" : 12345,
      "position" : { },
      "metrics" : { },
      "body" : "..."
    },
    "uuid" : "...",
    "edcTopic" : {
      "systemTopic" : true,
      "edcTopic" : true,
      "alertTopic" : true,
      "account" : "...",
      "asset" : "...",
      "semanticTopic" : "...",
      "leafName" : "...",
      "parentTopic" : "...",
      "grandParentTopic" : "...",
      "fullTopic" : "...",
      "topicParts" : [ "...", "..." ]
    }
  }, {
    "topic" : "...",
    "receivedOn" : 12345,
    "payload" : {
      "sentOn" : 12345,
      "position" : { },
      "metrics" : { },
      "body" : "..."
    },
    "uuid" : "...",
    "edcTopic" : {
      "systemTopic" : true,
      "edcTopic" : true,
      "alertTopic" : true,
      "account" : "...",
      "asset" : "...",
      "semanticTopic" : "...",
      "leafName" : "...",
      "parentTopic" : "...",
      "grandParentTopic" : "...",
      "fullTopic" : "...",
      "topicParts" : [ "...", "..." ]
    }
  } ]
}

GET /messages/count

Returns the count of all the Messages published under the account of the currently connected user.

Request Parameters
name type description default
endDate query End date of the date range requested. The parameter is expressed as a long counting the number of milliseconds since January 1, 1970, 00:00:00 GMT. If not specified it means current time. Alternatively, the date can be expressed as a string following the ISO 8601 format. 0
startDate query Start date of the date range requested. The parameter is expressed as a long counting the number of milliseconds since January 1, 1970, 00:00:00 GMT. If not specified it means no start date. Alternatively, the date can be expressed as a string following the ISO 8601 format. 0
topic query Optional parameter with the topic for which messages are requested. If not specified all messages on the account will be counted.  
Response Body
media type data type description
application/json CountResult (JSON) The count of requested Messages.
application/xml countResult (XML)

Example

Request
GET /messages/count
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "count" : 12345
}

POST /messages/publish

Publishes a new Message under the account of the currently connected user. The message will be published to the broker associated to this account. As such, devices and applications subscribed to the topic specified in the provided EdcMessage will receive a copy of the published message. Finally, all messages published to data topics - as opposed to control topics - will be stored in the back-end for later queries.

Request Parameters
name type description default constraints
qos query The quality of service to be used when publishing the provided message to the account broker 0 required
retain query The value of the retain flag to be used when publishing the provided message to the account broker false required
Request Body
media type data type description
application/json EdcMessage (JSON) The Message to be published. The topic field in the provided EdcMessage will be used to address the message to be published.
At present only XML is supported in the request body.
application/xml edcMessage (XML)

Example

Request
POST /messages/publish
Content-Type: application/json

                
{
  "topic" : "...",
  "receivedOn" : 12345,
  "payload" : {
    "sentOn" : 12345,
    "position" : {
      "longitude" : 12345.0,
      "latitude" : 12345.0,
      "altitude" : 12345.0,
      "precision" : 12345.0,
      "heading" : 12345.0,
      "speed" : 12345.0,
      "timestamp" : 12345,
      "satellites" : 12345,
      "status" : 12345
    },
    "metrics" : {
      "metric" : [ { }, { } ]
    },
    "body" : "..."
  },
  "uuid" : "...",
  "edcTopic" : {
    "systemTopic" : true,
    "edcTopic" : true,
    "alertTopic" : true,
    "account" : "...",
    "asset" : "...",
    "semanticTopic" : "...",
    "leafName" : "...",
    "parentTopic" : "...",
    "grandParentTopic" : "...",
    "fullTopic" : "...",
    "topicParts" : [ "...", "..." ]
  }
}
Response
HTTP/1.1 201 Created

DELETE /messages/purge

Delete all messages published on the account and reset account to the initial state without assets and topics.

Example of query in CURL :
curl --user 'clientId:client password' -X DELETE -k https://api-sandbox.everyware-cloud.com/v2/messages/purge.xml

Example

Request
DELETE /messages/purge
Content-Type: */*

                
...
Response
HTTP/1.1 204 No Content

GET /messages/searchByAsset

Returns the list of all the Messages published by the given Asset. Please keep in mind that when supplying an Asset as a query parameter in a URL, proper URL encoding is necessary for characters like '+' (replace it with '%2B') and '#' (replace it with '%23'). The startDate and endDate query parameters determine the time range for the messages returned; the timestamp of the returned messages will be in the interval between startDate and endDate.

If the flag MessagesResult.limitExceeded is set, the maximum number of entries to be returned has been reached, more data exist and can be read by moving the offset forward in a new request

If the parameter "sort" is set to "asc", messages are returned oldest first.

Request Parameters
name type description default constraints
asset query Mandatory parameter with the asset for which messages are requested.    
endDate query End date of the date range requested. The parameter is expressed as a long counting the number of milliseconds since January 1, 1970, 00:00:00 GMT. If not specified it means current time. Alternatively, the date can be expressed as a string following the ISO 8601 format. 0  
fetch query Specifies the amount of information requested. Allowed values are: meta, metrics, all. "meta" returns only the topic and received on information; "metrics" returns "meta" plus all the metrics included in the message; "all" returns the whole message including its binary payload. metrics  
limit query Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. 50 required
offset query Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. 0 required
sort query specify the timestamp sort order for messages : "asc" return messages in ascending order (oldest first), "desc" or not set, messages are returned newest first desc  
startDate query Start date of the date range requested. The parameter is expressed as a long counting the number of milliseconds since January 1, 1970, 00:00:00 GMT. If not specified it means no start date. Alternatively, the date can be expressed as a string following the ISO 8601 format. 0  
Response Body
media type data type description
application/json MessagesResult (JSON) The list of requested Messages.
application/xml messagesResult (XML)

Example

Request
GET /messages/searchByAsset
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "limitExceeded" : true,
  "message" : [ {
    "topic" : "...",
    "receivedOn" : 12345,
    "payload" : {
      "sentOn" : 12345,
      "position" : { },
      "metrics" : { },
      "body" : "..."
    },
    "uuid" : "...",
    "edcTopic" : {
      "systemTopic" : true,
      "edcTopic" : true,
      "alertTopic" : true,
      "account" : "...",
      "asset" : "...",
      "semanticTopic" : "...",
      "leafName" : "...",
      "parentTopic" : "...",
      "grandParentTopic" : "...",
      "fullTopic" : "...",
      "topicParts" : [ "...", "..." ]
    }
  }, {
    "topic" : "...",
    "receivedOn" : 12345,
    "payload" : {
      "sentOn" : 12345,
      "position" : { },
      "metrics" : { },
      "body" : "..."
    },
    "uuid" : "...",
    "edcTopic" : {
      "systemTopic" : true,
      "edcTopic" : true,
      "alertTopic" : true,
      "account" : "...",
      "asset" : "...",
      "semanticTopic" : "...",
      "leafName" : "...",
      "parentTopic" : "...",
      "grandParentTopic" : "...",
      "fullTopic" : "...",
      "topicParts" : [ "...", "..." ]
    }
  } ]
}

GET /messages/searchByMetric

Returns the list of all the Messages published under the given Topic with the specific range of values for one of its metrics. Depending on your metric data indexing, the metrics may be stored in MetricsByValue or MetricsByTimestamp. In the first case, the range on values are mandatory, while the date range is optional and viceversa in the latter case. If the index metrics data is set to "none", the query is not available. Wild cards on the topic name can be used to aggregate messages at the different topic levels. For example, a topic "edcguest/+/bus/#" can used to return all messages published under the edcguest account, across all the assets, and for all the buses. Please keep in mind that when supplying a Topic as a query parameter in a URL, proper URL encoding is necessary for characters like '+' (replace it with '%2B') and '#' (replace it with '%23'). The startDate and endDate query parameters determine the time range for the messages returned; the timestamp of the returned messages will be in the interval between startDate and endDate.

If the flag MessagesResult.limitExceeded is set, the maximum number of entries to be returned has been reached, more data exist and can be read by moving the offset forward in a new request

The messages returned are sorted. If the parameter "sortType" is set to "time", messages will be sorted by timestamp, if set to "value" or not set, messages will be sorted by metric value.
If the parameter "sort" is set to "asc", messages are returned oldest or smallest first.

Request Parameters
name type description default constraints
endDate query End date of the date range requested. The parameter is expressed as a long counting the number of milliseconds since January 1, 1970, 00:00:00 GMT. If not specified it means current time. Alternatively, the date can be expressed as a string following the ISO 8601 format. Mandatory for metrics data index by timestamp.    
limit query Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. 50 required
max query Maximal value of the range of the metric to be applied. Mandatory for metrics data index by value.  
metric query Mandatory parameter with the name of the metric used for the data filtering.  
min query Minimal value of the range of the metric to be applied. Mandatory for metrics data index by value.  
offset query Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. 0 required
sort query specify the timestamp or value sort order for messages : "asc" return messages in ascending order (oldest or smallest first), "desc" or not set, messages are returned newest or greatest first desc  
startDate query Start date of the date range requested. The parameter is expressed as a long counting the number of milliseconds since January 1, 1970, 00:00:00 GMT. If not specified it means no start date. Alternatively, the date can be expressed as a string following the ISO 8601 format. Mandatory for metrics data index by timestamp.    
topic query Mandatory parameter with the topic for which messages are requested.    
type query Mandatory parameter with the type of the metric used for the data filtering. Allowed types are: string, double, int, float, long, boolean.  
Response Body
media type data type description
application/json MessagesResult (JSON) The list of requested Messages.
application/xml messagesResult (XML)

Example

Request
GET /messages/searchByMetric
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "limitExceeded" : true,
  "message" : [ {
    "topic" : "...",
    "receivedOn" : 12345,
    "payload" : {
      "sentOn" : 12345,
      "position" : { },
      "metrics" : { },
      "body" : "..."
    },
    "uuid" : "...",
    "edcTopic" : {
      "systemTopic" : true,
      "edcTopic" : true,
      "alertTopic" : true,
      "account" : "...",
      "asset" : "...",
      "semanticTopic" : "...",
      "leafName" : "...",
      "parentTopic" : "...",
      "grandParentTopic" : "...",
      "fullTopic" : "...",
      "topicParts" : [ "...", "..." ]
    }
  }, {
    "topic" : "...",
    "receivedOn" : 12345,
    "payload" : {
      "sentOn" : 12345,
      "position" : { },
      "metrics" : { },
      "body" : "..."
    },
    "uuid" : "...",
    "edcTopic" : {
      "systemTopic" : true,
      "edcTopic" : true,
      "alertTopic" : true,
      "account" : "...",
      "asset" : "...",
      "semanticTopic" : "...",
      "leafName" : "...",
      "parentTopic" : "...",
      "grandParentTopic" : "...",
      "fullTopic" : "...",
      "topicParts" : [ "...", "..." ]
    }
  } ]
}

GET /messages/searchByTopic

Returns the list of all the Messages published under the given topic. Wild cards on the topic name can be used to aggregate messages at the different topic levels. For example, a topic "edcguest/+/bus/#" can used to return all messages published under the edcguest account, across all the assets, and for all the buses. Please keep in mind that when supplying a Topic as a query parameter in a URL, proper URL encoding is necessary for characters like '+' (replace it with '%2B') and '#' (replace it with '%23'). It is also required that the 'full topic' be supplied. This consists of the 'topic prefix' and the 'semantic topic'. The 'topic prefix' is account/asset and the semantic topic is everything after. So, at minimum the topic supplied in this query must be at least three levels deep. The startDate and endDate query parameters determine the time range for the messages returned; the timestamp of the returned messages will be in the interval between startDate and endDate.

If the flag MessagesResult.limitExceeded is set, the maximum number of entries to be returned has been reached, more data exist and can be read by moving the offset forward in a new request

If the parameter "sort" is set to "asc", messages are returned oldest first.

Request Parameters
name type description default constraints
endDate query End date of the date range requested. The parameter is expressed as a long counting the number of milliseconds since January 1, 1970, 00:00:00 GMT. If not specified it means current time. Alternatively, the date can be expressed as a string following the ISO 8601 format. 0  
fetch query Specifies the amount of information requested. Allowed values are: meta, metrics, all. "meta" returns only the topic and received on information; "metrics" returns "meta" plus all the metrics included in the message; "all" returns the whole message including its binary payload. metrics  
limit query Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. 50 required
offset query Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. 0 required
sort query specify the timestamp sort order for messages : "asc" return messages in ascending order (oldest first), "desc" or not set, messages are returned newest first desc  
startDate query Start date of the date range requested. The parameter is expressed as a long counting the number of milliseconds since January 1, 1970, 00:00:00 GMT. If not specified it means no start date. Alternatively, the date can be expressed as a string following the ISO 8601 format. 0  
topic query Mandatory parameter with the topic for which messages are requested.    
Response Body
media type data type description
application/json MessagesResult (JSON) The list of requested Messages.
application/xml messagesResult (XML)

Example

Request
GET /messages/searchByTopic
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "limitExceeded" : true,
  "message" : [ {
    "topic" : "...",
    "receivedOn" : 12345,
    "payload" : {
      "sentOn" : 12345,
      "position" : { },
      "metrics" : { },
      "body" : "..."
    },
    "uuid" : "...",
    "edcTopic" : {
      "systemTopic" : true,
      "edcTopic" : true,
      "alertTopic" : true,
      "account" : "...",
      "asset" : "...",
      "semanticTopic" : "...",
      "leafName" : "...",
      "parentTopic" : "...",
      "grandParentTopic" : "...",
      "fullTopic" : "...",
      "topicParts" : [ "...", "..." ]
    }
  }, {
    "topic" : "...",
    "receivedOn" : 12345,
    "payload" : {
      "sentOn" : 12345,
      "position" : { },
      "metrics" : { },
      "body" : "..."
    },
    "uuid" : "...",
    "edcTopic" : {
      "systemTopic" : true,
      "edcTopic" : true,
      "alertTopic" : true,
      "account" : "...",
      "asset" : "...",
      "semanticTopic" : "...",
      "leafName" : "...",
      "parentTopic" : "...",
      "grandParentTopic" : "...",
      "fullTopic" : "...",
      "topicParts" : [ "...", "..." ]
    }
  } ]
}

POST /messages/store

Stores a new Message under the account of the currently connected user. In this case, the provided message will only be stored in the back-end database and it will not be forwarded to the message broker.

Request Body
media type data type description
application/json EdcMessage (JSON) The Message to be stored. The topic field in the provided EdcMessage will be used to address the message to be stored.
Messages marshalled in XML or JSON format are supported as long as the Accept HTTP header is set accordingly.
application/xml edcMessage (XML)

Example

Request
POST /messages/store
Content-Type: application/json

                
{
  "topic" : "...",
  "receivedOn" : 12345,
  "payload" : {
    "sentOn" : 12345,
    "position" : {
      "longitude" : 12345.0,
      "latitude" : 12345.0,
      "altitude" : 12345.0,
      "precision" : 12345.0,
      "heading" : 12345.0,
      "speed" : 12345.0,
      "timestamp" : 12345,
      "satellites" : 12345,
      "status" : 12345
    },
    "metrics" : {
      "metric" : [ { }, { } ]
    },
    "body" : "..."
  },
  "uuid" : "...",
  "edcTopic" : {
    "systemTopic" : true,
    "edcTopic" : true,
    "alertTopic" : true,
    "account" : "...",
    "asset" : "...",
    "semanticTopic" : "...",
    "leafName" : "...",
    "parentTopic" : "...",
    "grandParentTopic" : "...",
    "fullTopic" : "...",
    "topicParts" : [ "...", "..." ]
  }
}
Response
HTTP/1.1 201 Created

GET /messages/{MsgID}

Returns the Message with a given uuid. Multiple comma separated uuids can be used for this query.

Request Parameters
name type description default
MsgID path the uuid of the Message  
fetch query Specifies the amount of information requested. Allowed values are: meta, metrics, all. "meta" returns only the topic and received on information; "metrics" returns "meta" plus all the metrics included in the message; "all" returns the whole message including its binary payload. metrics
Response Body
media type data type description
application/json MessagesResult (JSON) The list of requested Messages.
application/xml messagesResult (XML)

Example

Request
GET /messages/{MsgID}
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "limitExceeded" : true,
  "message" : [ {
    "topic" : "...",
    "receivedOn" : 12345,
    "payload" : {
      "sentOn" : 12345,
      "position" : { },
      "metrics" : { },
      "body" : "..."
    },
    "uuid" : "...",
    "edcTopic" : {
      "systemTopic" : true,
      "edcTopic" : true,
      "alertTopic" : true,
      "account" : "...",
      "asset" : "...",
      "semanticTopic" : "...",
      "leafName" : "...",
      "parentTopic" : "...",
      "grandParentTopic" : "...",
      "fullTopic" : "...",
      "topicParts" : [ "...", "..." ]
    }
  }, {
    "topic" : "...",
    "receivedOn" : 12345,
    "payload" : {
      "sentOn" : 12345,
      "position" : { },
      "metrics" : { },
      "body" : "..."
    },
    "uuid" : "...",
    "edcTopic" : {
      "systemTopic" : true,
      "edcTopic" : true,
      "alertTopic" : true,
      "account" : "...",
      "asset" : "...",
      "semanticTopic" : "...",
      "leafName" : "...",
      "parentTopic" : "...",
      "grandParentTopic" : "...",
      "fullTopic" : "...",
      "topicParts" : [ "...", "..." ]
    }
  } ]
}