Skip to content

Versioning of Messages⚓︎

Messages evolve over time. Additional information might be added to a message or existing properties might change, all with the intention to make the newer version of a message more valuable for you. Usually, all changes to a message happen in a backwards-compatible way, which your consuming applications should be able to handle gracefully. You do not have to adjust your integration until, for example, you would like to make use of the additional information that was introduced in the newer version of the message.

backwards-compatible changes

The following changes are considered backwards-compatible:

  • bugfixes
  • addition of new properties
  • shortening of string lengths
  • changing the sequence of properties
  • addition of enumeration values for string-enumerations declared as x-extensible-enum
  • addition of new message_types to the topic

Make sure to handle such changes gracefully when consuming messages.

However, sometimes it is necessary to change the structure of a message in such a way that the changes are not backwards-compatible (“breaking changes”). Even in this case, your integration will not break, because the new version of the message that contains breaking changes will initially be added in addition to the existing version of the message. It is then up to you to decide when you want to switch to the newer version, as this usually requires some adjustments to your code that is deserializing and handling the message. Read on to find out more about our versioning rules for messages and message topics.

Message types and topics⚓︎

  • Each message has a message type which uniquely identifies what kind of message it is.
  • A message topic is a collection of one or more message types. You can only subscribe to message topics and not to individual message types.
  • When subscribing to a message topic, you will get access to an AMQP queue. This queue delivers messages of all of the topic’s message types.
  • All messages within a message topic are delivered in the exact order they occurred.

How versioning works⚓︎

Versioning happens for both, messages as well as topics:

  • Messages: all messages have a message_version1 such as 2.4.3 which follows semantic versioning using the MAJOR.MINOR.PATCH schema:
    • MAJOR will be increased on breaking changes, which are not backwards-compatible
    • MINOR will be increased on new, backwards-compatible features
    • PATCH will be increased on backwards-compatible, small changes or bugfixes
  • Topics: all topics only have a major version based on semantic versioning such as 5

When subscribing to a topic, you actually subscribe to a specific version of the topic, such as VehicleChange_v1. Within this topic, the MAJOR part of a message_version will never change. In other words, all messages therein will only receive backwards-compatible changes (MINOR or PATCH part increases) and never breaking changes.

When a new major version of a message type is introduced, a new message topic with increased major version becomes available to deliver this new message version. Messages of the new major version are only published on the new topic, whereas messages of the previous version are still published to the existing topic. This ensures that your existing consumers don’t break and you have time to upgrade to the new version.

Recommended

When you add a new integration to one of the Messaging API’s topics, it is strongly recommended you subscribe to the newest (=highest) version of a topic.

Example⚓︎

The following example shows a possible sequence of changes for messages and outlines how version numbers of the messages and corresponding topic adapt to these changes.

Step 1⚓︎

Let’s assume that you have initially subscribed to topic VehicleChange_v7.

Topic VehicleChange_v7 publishes:

  • message_type:VehicleCreated with message_version:3.0.0
  • message_type:VehicleDataChanged with message_version:3.0.0
  • message_type:VehicleDeleted with message_version:3.0.0

Step 2⚓︎

At some point, the INVERS OneAPI adds a new property to the VehicleDataChanged message type. Because the new property is a backwards-compatible addition, only the MINOR version of the message increases.

Topic VehicleChange_v7 (remains on the same version) publishes:

  • message_type:VehicleCreated with message_version:3.0.0
  • message_type:VehicleDataChanged with message_version:3.1.0
  • message_type:VehicleDeleted with message_version:3.0.0

You do not need to change your integration at this point. Everything keeps running without any need for adjustments on your side. Only if you want to use the newly added property you would need to add it to your code that is responsible for deserializing and handling messages of this message type.

Step 3⚓︎

Let’s assume that a new major version of a message is approaching. It contains backwards-incompatible changes to the message. In order not to break existing integrations, the topic VehicleChange_v7 remains untouched. Instead, a new topic version VehicleChange_v8 will be introduced and both topic versions are available to subscribe to them.

Topic VehicleChange_v7 (unchanged) still publishes:

  • message_type:VehicleCreated with message_version:3.0.0
  • message_type:VehicleDataChanged with message_version:3.1.0
  • message_type:VehicleDeleted with message_version:3.0.0

New topic VehicleChange_v8 publishes:

  • message_type:VehicleCreated with message_version:3.0.0
  • message_type:VehicleDataChanged with message_version:4.0.0
  • message_type:VehicleDeleted with message_version:3.0.0

As a consumer, you can then decide:

  • Stick with VehicleChange_v7. In this case you do not have to do anything. Of course, you will not get access to any new functionality or information which might have been introduced in the new version.
  • Switch to VehicleChange_v8 in order to start using the most recent version of the message. You can do this whenever you want to.

Upgrading to newer topic versions⚓︎

There are times when you want to switch to a newer topic version (see above). Depending on your integration this might require you to make some adjustments to your code.

The recommended sequence when upgrading from topic version a to b is:

  1. Continue consuming and processing messages for version a
  2. Add OneAPI subscription on topic b
  3. Implement consuming of messages for version b (but not necessarily process and use the messages).
    • Test if the new messages are properly interpreted.
    • Optional: make “dry runs” for processing the new messages
  4. Switch from a to b in your integration (don’t consume a any longer)
  5. Remove OneAPI subscription on topic a

  1. The message_version is contained in each message’s metadata property and in the message’s AMQP headers. 

Back to top