Messages

The following resources are applicable:

/messages

Mount Point: /v2/messages

GET

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 -

Parameters

name description type default
limit Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 50
offset Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 0
startDate 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. query 0
endDate 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. query 0
fetch 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. query metrics
sort specify the timestamp sort order for messages : "asc" return messages in ascending order (oldest first), "desc" or not set, messages are returned newest first query desc

Response Body

element: messagesResult
media types: application/xml
application/json

The list of requested Messages.

DELETE

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.

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:
* edcguest/Device_Id_01/car/route/two : delete all messages for this topic (only asset Device_Id_01 is concerned)
* edcguest/Device_Id_01/tram/# : delete all messages for asset Device_Id_01 under tram topic (including all subtopics)
* edcguest/+/car/route/one : delete all messages for all assets under car/route/one topic and delete topic car/route/one
* edcguest/+/car/# : delete all messages for all assets under car and all subtopics and delete topic car and all subtopics
* edcguest/Device_Id_01/# : delete 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:

  • / = %2F
  • + = %2B
  • # = %23
  • Example of query in CURL :
    curl --user 'clientId:client 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)

    Parameters

    name description type default
    topic see examples above. query
    startYear The parameter is expressed as an int. query -1
    startWeek number of the start week in startYear to be deleted. The parameter is expressed as an int. query -1
    endYear The parameter is expressed as an int. query -1
    endWeek number of the end week in endYear to be deleted. The parameter is expressed as an int. query -1
    purge if set to true, TopicsByAccount, TopicsByAssets and AssetsByAccount will be deleted. query false

    /messages/{MsgID}

    Mount Point: /v2/messages/{MsgID}

    GET

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

    Parameters

    name description type default
    MsgID the uuid of the Message path
    fetch 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. query metrics

    Response Body

    element: messagesResult
    media types: application/xml
    application/json

    The list of requested Messages.

    /messages/count

    Mount Point: /v2/messages/count

    GET

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

    Parameters

    name description type default
    topic Optional parameter with the topic for which messages are requested. If not specified all messages on the account will be counted. query
    startDate 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. query 0
    endDate 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. query 0

    Response Body

    element: countResult
    media types: application/xml
    application/json

    The count of requested Messages.

    /messages/publish

    Mount Point: /v2/messages/publish

    POST

    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.

    Parameters

    name description type default
    qos The quality of service to be used when publishing the provided message to the account broker query 0
    retain The value of the retain flag to be used when publishing the provided message to the account broker query false

    Request Body

    element: message
    media types: application/xml

    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.

    POST

    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.

    Parameters

    name description type default
    qos The quality of service to be used when publishing the provided message to the account broker query 0
    retain The value of the retain flag to be used when publishing the provided message to the account broker query false

    Request Body

    element: strMsg
    media types: application/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 JSON is supported in the request body.

    /messages/purge

    Mount Point: /v2/messages/purge

    DELETE

    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

    /messages/searchByAsset

    Mount Point: /v2/messages/searchByAsset

    GET

    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.

    Parameters

    name description type default
    asset Mandatory parameter with the asset for which messages are requested. query
    limit Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 50
    offset Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 0
    startDate 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. query 0
    endDate 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. query 0
    fetch 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. query metrics
    sort specify the timestamp sort order for messages : "asc" return messages in ascending order (oldest first), "desc" or not set, messages are returned newest first query desc

    Response Body

    element: messagesResult
    media types: application/xml
    application/json

    The list of requested Messages.

    /messages/searchByMetric

    Mount Point: /v2/messages/searchByMetric

    GET

    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.

    Parameters

    name description type default
    topic Mandatory parameter with the topic for which messages are requested. query
    limit Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 50
    offset Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 0
    startDate 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. query
    endDate 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. query
    metric Mandatory parameter with the name of the metric used for the data filtering. query
    type Mandatory parameter with the type of the metric used for the data filtering. Allowed types are: string, double, int, float, long, boolean. query
    min Minimal value of the range of the metric to be applied. Mandatory for metrics data index by value. query
    max Maximal value of the range of the metric to be applied. Mandatory for metrics data index by value. query
    sort 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 query desc

    Response Body

    element: messagesResult
    media types: application/xml
    application/json

    The list of requested Messages.

    /messages/searchByTopic

    Mount Point: /v2/messages/searchByTopic

    GET

    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.

    Parameters

    name description type default
    topic Mandatory parameter with the topic for which messages are requested. query
    limit Maximum number of entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 50
    offset Starting offset for the entries to be returned. Note that an error will be returned if the maximum allowed value is exceeded. query 0
    startDate 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. query 0
    endDate 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. query 0
    fetch 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. query metrics
    sort specify the timestamp sort order for messages : "asc" return messages in ascending order (oldest first), "desc" or not set, messages are returned newest first query desc

    Response Body

    element: messagesResult
    media types: application/xml
    application/json

    The list of requested Messages.

    /messages/store

    Mount Point: /v2/messages/store

    POST

    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

    element: message
    media types: application/xml

    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.

    POST

    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

    element: strMsg
    media types: application/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. Notice that as the same behaviour of POST above but differences from the accepted media-type.