Messages in AMPS

Communication between applications and the AMPS server uses AMPS messages. AMPS messages are received or sent for every operation in AMPS. Each AMPS message has a specific type and consists of a set of headers and a payload. The headers are defined by AMPS and formatted according to the protocol specified for the connection. Typically, applications use the standard amps protocol which uses a JSON document for headers. The payload, if one is present, is the content of the message and is in the format specified by the message type.

Messages received from AMPS have the same format as messages to AMPS. These messages also have a specific type, with a header formatted according to the protocol and a payload of the specified message type. For example, AMPS uses ack messages, short for acknowledgment, to report the status of commands. AMPS uses publish messages to deliver messages on a subscription, and so on for other commands and other messages.

Let's consider a complete interaction between an application and the AMPS server as an example. When a client subscribes to a topic in AMPS, the client sends a subscribe message to AMPS that contains the information about the requested subscription and, by default, a request for an acknowledgment that the subscription has been processed. AMPS returns an ack message when the subscription is processed that indicates whether the subscription succeeded or failed, and then begins providing publish messages for new messages on the subscription. The publish messages continue as messages that match the subscription arrive at the AMPS server. If the application needs to stop the subscription, the application sends an unsubscribe message to the AMPS server, indicating the subscription to end. Once the AMPS server processes the unsubscribe message, the server will no longer send messages for that subscription to the application. Should the application disconnect, the AMPS server removes all subscriptions for that connection (whether or not the application sends an unsubscribe command first).

Messages to and from AMPS are described in more detail in the AMPS Command Reference, available on the 60East website and included in the AMPS client SDKs.

In this version of AMPS, the communication transports used by AMPS accept message sizes of up to 200MB in a single command to AMPS. Messages larger than 200MB may be rejected by the transport as invalid. Should your use of AMPS require larger message sizes, contact 60East support.

This version of AMPS limits messages to 200MB in total size

Introduction to AMPS Headers

The AMPS Command Reference contains a full list of headers for each command. The table below lists some commonly used headers.

Header	Description
Topic	The topic that the message applies to. For commands to AMPS, this is the topic that AMPS will apply the command to. For messages from AMPS, this is the topic from which the message originated.
Command	The command type of the message. Each message has a specific command type. For example, messages that contain data from a query over a SOW topic have a command of sow, while messages that contain data from a publish command have a command of publish and messages that acknowledge a command to AMPS have a command type of ack.
CommandId	An identifier used to correlate responses from AMPS with an initial command. For example, ack messages returned by AMPS contain the CommandId provided with the command they acknowledge and subscriptions can be updated or removed using the CommandId provided with the subscribe command.
SowKey	For messages received from a State of the World (or SOW) topic, an identifier that AMPS assigns to the record for this message. SOW topics are described the State of the World Topics section. This header is included on messages from a SOW topic by default. AMPS will omit this header when the subscription or SOW query includes the no_sowkey option.
CorrelationId	A user-specified identifier for the message. Publishers can set this identifier on messages. AMPS does not parse, change, or interpret this identifier in any way. This header is limited to characters used in Base64 encoding.
Status	Set on ack messages to indicate the results of the command, such as Success or Failure.
Reason	Set on ack messages to indicate the reason for the Status acknowledgment.
Timestamp	Optionally set on publish messages and sow messages to indicate the time at which the local AMPS instance processed the message. To receive a timestamp, the SOW query or subscription must include the timestamp option on the command that creates the subscription or runs the query. The timestamp is returned in ISO-8601 format.

This section presents a few of the commonly used headers. See the AMPS Command Reference for a full description of AMPS messages.

AMPS does not provide the ability to add custom header fields. However, AMPS composite message types provide an easy way to add an additional section to a message type that contains metadata for the message. Since composite message type parts fully support AMPS content filtering, this approach provides more flexibility and allows for more sophisticated metadata than simply adding a header field. See the Composite Messages section for details.