Skip to content

Versioning of Events⚓︎

Events evolve over time. Additional information might be added to an event or existing properties might change, all with the intention to make the newer version of an event more valuable for you. Usually, all changes to an event 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 event.

backwards-compatible changes

The following changes are considered backwards-compatible:

  • 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 event types to the topic

Make sure to handle such changes gracefully when consuming events.

However, sometimes it is necessary to change the structure of an event 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 event that contains breaking changes will initially be added in addition to the existing version of the event (in a new event topic). It is then up to you to decide when you want to switch to the newer version of the topic, as this usually requires some adjustments to your code that is deserializing and handling the event. Read on to find out more about our versioning rules for events and event topics.

Event types and topics⚓︎

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

How versioning works⚓︎

When subscribing to a topic, you actually subscribe to a specific version of that topic, such as VehicleChange_v1. All events published within a topic are guaranteed to be backwards-compatible, so you can be sure there will be no breaking changes within a topic you have subscribed to. However, the events within a topic might (and probably will) receive backwards-compatible changes, e.g. new properties.

When a new major version of an event type is introduced, a new event topic with increased major version becomes available to deliver this new event version. Events of the new major version are only published on the new topic, whereas events 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 Events 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 events and outlines how version numbers of the events 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:

  • Event type: VehicleCreated
  • Event type: VehicleChanged
  • Event type: VehicleArchived

Step 2⚓︎

At some point, the INVERS API adds a new property to the VehicleChanged event type. Because the new property is a backwards-compatible addition, this is possible without breaking your integration.

Topic VehicleChange_v7 (remains on the same version) publishes:

  • Event type: VehicleCreated
  • Event type: VehicleChanged (with the new property)
  • Event type: VehicleArchived

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 events of this event type.

Step 3⚓︎

Let’s assume that a new major version of an event is approaching. It contains breaking changes to the VehicleCreated event. In order not to break existing integrations, the topic VehicleChange_v7 remains untouched. Instead, a new topic version VehicleChange_v8 will be introduced.

Topic VehicleChange_v7 (unchanged) still publishes:

  • Event type: VehicleCreated
  • Event type: VehicleChanged
  • Event type: VehicleArchived

New topic VehicleChange_v8 publishes:

  • Event type: VehicleCreated (with incompatible, new schema)
  • Event type: VehicleChanged
  • Event type: VehicleArchived

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 event. 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 events for version a
  2. Add API subscription on topic b
  3. Implement consuming of events for version b (but not necessarily process and use the events).
    • Test if the new events are properly interpreted.
    • Optional: make “dry runs” for processing the new events
  4. Switch from a to b in your integration (don’t consume a any longer)
  5. Remove API subscription on topic a