Skip to content

Message Format⚓︎

All messages delivered trough the Messaging API share a common structure and follow the same rules.

Structure⚓︎

The payload of all messages consist of metadata and data.

Example

{
  "metadata": {
    "message_id": "01F1FHJ7SHQK5MGF69B8K2346E",
    "message_type": "VehicleStateReceived",
    "occurred_at": "2020-01-30T13:22:05Z",
    "version": "2.0.0",
    "flow_id": "804f2161-a15c-420f-8f21-61a15c320f68"
  },
  "data": {
      // message's data content
  }
}

metadata⚓︎

All messages share the same kind of metadata:

  • message_id uniquely identifies each message (allows you to perform duplication checks if needed)
  • occurred_at is a timestamp indicating when the message was produced

The following values are additionally available as AMQP headers when receiving a message:

  • message_type tells you what type of message it is. This is especially useful if there are multiple possible message types within a message topic.
  • version is the message type’s version using semantic versioning.
  • flow_id can be matched with the X-Invers-Flow-ID header if the message directly results from an API call.

data⚓︎

Contains the message’s data. The content depends on the message_type.

Message Content⚓︎

The messages share many of the formatting rules and schemas of the corresponding REST APIs. This way, it is easy to use common data models for both.

JSON⚓︎

The message payloads are returned as JSON (application/json).

Date Time⚓︎

Date and time values are in UTC in the following ISO 8601 compatible format: 2014-10-17T14:30:00Z

Headers⚓︎

The following headers are included when consuming each message:

  • Flow-ID
  • Message-Type
  • Message-Version

Their values are equal to their corresponding properties within the metadata properties of the message. They are included to assist in deserialization of the message within your application (see parsing messages).

Back to top