Service Versioning & Compatibility

Manager Service API supports service maintainability by offering two levels of versioning to handle service changes effectively. This chapter describes the two levels of versioning.

MSA does not offer built-in support for versioning multiple iterations of the same service. However, it does allow services to evolve over time. As long as changes are compatible, you can extend services without issues. At a basic level, we distinguish the following types of changes:

  • Non-Breaking Changes: Services can be updated without changing their version. This means new features and improvements can be added while ensuring backward compatibility with existing clients.
  • Breaking Changes: When changes are not compatible with older versions.

In the context of one WinCC OA version, most changes can be considered non-breaking, as both the server and client will be updated simultaneously. However, in the context of an entire WinCC OA distributed system, older clients may still be in use, and for those clients, such changes could be breaking. Whether these changes are allowed depends on the possibility of older clients being present in the plant.

Several scenarios must be considered for compatibility:

  • Client/remote scenario: This issue can occur with remote managers when different patch levels are used, or when the deployment between the server and client is not synchronized or has an offset.
  • Distributed systems: In distributed systems, it is possible for two systems to have different patch levels, or for the project deployment to use different versions.

In both situations, different versions of the service and client may be in use. We can identify two main cases:

  • Older client communicating with a newer service (this is the most important case)
  • Newer client communicating with an older service

By following some versioning rules, Manager Service API creates a stable and predictable environment for service updates and client interactions.

Non-Breaking Changes Across All Protocols

  • Adding a new service: You can always create new services and share them in a manager. Since no one is relying on the new service yet, there are no compatibility issues.
  • Adding a new method to an existing service: You can add new methods to an existing service without causing compatibility problems, as no one is depending on the new method yet.

Breaking Changes Across All Protocols

  • Renaming a service or method: Since others may depend on the current method name, renaming an existing method can cause compatibility issues. A common approach is to define two methods: one with the old name and one with the new name, but implement both just once on server. The old method can be marked as deprecated, allowing it to be removed after a reasonable period.
  • Removing a service or method: Similar to renaming, removing a method also creates compatibility issues. You should only remove a method if you are certain that no one is still using it.

vRPC Compatibility

Compatibility depends on whether the request and response messages are compatible for a service method. Consider this in the implementation of the service and the usage of the stub, as they are responsible for using and interpreting the request and response messages.

Request Message Compatibility

The following techniques can be used to implement compatibility for requests in the service:

  • Checking the data type of the request variable.
  • Treating keys inside a mapping variable as optional.
  • Checking the values in an array accordingly.

Response Message Compatibility

The return value of a service method must be interpretable in a reverse-compatible manner on the client.

The implementation of the service considers compatibility by, for example:

  • Returning values according to the request (old request version returns old response).
  • Adding and removing keys inside a mapping variable.
  • Adding and never removing values in an array.

The implementation of the client considers compatibility by, for example:

  • Checking the data type of the variable (which may result in an error on the client side).
  • Ignoring unknown keys inside a mapping variable (if the necessary keys are consistent).
  • Checking the values in an array accordingly.

Common Compatibility

  • Adding a value to an enum. Depending on how the enum is written into the variable:

    • By name: Adding new names is possible, changing values is possible.
    • By numeric value: Adding new values is possible, changing names is possible.

  • Behavior compatibility:

    Ensuring that the behavior of the service remains consistent across versions is crucial. This includes maintaining the same logical flow, handling edge cases similarly, and ensuring that any changes do not alter the expected outcomes for existing clients.