JSON Messages - A Quick Primer

AMPS supports a variety of data formats. For simplicity, this guide uses JSON in the examples. This section describes the basic JSON format.

JSON Messages - A Quick Primer

AMPS includes support for a wide variety of message types, as well as the ability to develop custom message types and to send binary payloads. This section focuses on JSON as the main message type used for samples in this guide. We use JSON for the guide because the format is simple, easily readable, and already in use in many environments.

JSON format is a simple, standardized message format. JSON has two basic constructs:

• Objects that consist of key / value pairs

• Arrays of values

JSON supports hierarchical construction: the value for a key can be a single value, an array of values, or another set of key/value pairs. For example, the following JSON message includes two nested sets of key value pairs. Notice that a key only needs to be unique within each set of values -- the name value for the ship does not conflict with the name value for the character.

{
    "id" : 73,
    "character" : {
        "name" : "Han Solo",
        "occupation" : "smuggler",
        "ship" : {
            "name"  : "Millennium Falcon",
            "speed" : ".5 past light speed",
            "cargo" : [ "widgets", "baskets", "spice"]
        }
    }
}

Many AMPS applications use JSON as the payload. In addition, the amps protocol used to send commands to AMPS represents commands in a simplified subset of JSON. For example, a publish command might look like:

{"c":"publish","t":"test-topic"}{ "id" : 1, "message" : "Hello, World!" }

The command to AMPS, using the amps protocol, can be treated as a JSON document which contains the header information for AMPS -- in this case, a publish to the topic test-topic. The header is followed by the message body, the payload of the command.

While the amps protocol is implemented as a subset of JSON, you can use any message type with the amps protocol. The header for the command will still be JSON, while the body can be in the message type of your choice, as in the sample below, which publishes to an XML topic:

{ "c":"publish","t":"xml-topic"}<example><id>1</id><message>Hello, world!</message></example>

The AMPS client libraries create and parse AMPS headers. For example, the publish method in the AMPS client libraries creates the appropriate header for a publish command based on the provided parameters.

Your applications use the Message and Command interfaces of the AMPS client libraries to work with the AMPS headers. There is no need for your application to parse or serialize the AMPS headers directly.

The AMPS client libraries handle creating and parsing AMPS headers. They do not parse or interpret the payload data on a received Message, instead the payload is returned as a sequence of bytes (or as a string).

There's one exception to this: the JavaScript client can optionally deserialize JSON messages into objects.