How to implement versioning in Lagom microservices?

How to implement versioning in Lagom microservices?

Lagom doesn't provide any solution, plugin or feature that enables API versioning. However you can use the following to decide and pick what works best for you:

When versioning you must keep in mind both the service endpoints and payloads and the topics and events.

Endpoints and payloads

If your new versions are breaking changes you will need to expose the new endpoints on a separate namespace. To do that you have few choices:

  1. Create a new, thin microservice that serves the new API and deploy it under a different name in front of the old service. Clients would then import MyService or MyServiceV2. You would have two deployment units (MyService and MyService2) but only one of them would store data or emit events over a broker.
  2. Create a new, thin microservice that serves the old API and deploy it in front of the new one. This is similar to #1 but you put the database behind the new API and use the thin proxy for laggard users. Whether you chose this option or the previous one depends on which users should be penalized with the extra latency
  3. Duplicate all endpoints of your service and include a prefix. In this case you deploy a single service with a lot of duplicated code inside. All endpoints and payloads are exposed in a single -api project . This will be easier to deploy but will create confusion on the service implementation and especially will leak the version complexity on your clients as they all will see both versions of the API. Note how the first two options implied publishing completely separate -api for each version.

Topics and Events

This is quite similar but this time your new schema is a separate topic on your broker.

  1. Following the example where the new API is deployed as a thin layer, if we're creating a topic with an improved API that's not backwards compatible then the thin layer service will have to consume the old topic and do the conversion.
  2. Similarly, if we move the old API to the thin layer and keep the logic and database on the new service, the thin layer will have to consume the new topic and downgrade the content to the old version
  3. Finally, if we deploy both versions on a single service then you'll need two separate TopicProducer's

Lagom does not support implementing two Service into a single deployment unit which is why in the above examples the only way to keep your -api separate is creating separate deployment units.

Finally, there's an edge case that needs highlighted: if your changes only happen on the payload of your ServiceCalls (the paths remain the same and the topic and events also remain the same) you could try to use tuned MessageSerializers. You could have a Message serializer with rich content negotiation so that clients may decide on the Accepted: request header what format they are sending and expect as a response (e.g.application/vnd.myapplication.user.v1+json)

    • Related Articles

    • Can I customize error handling in Lagom?

      Yes, the best way to customize error handling in Lagom is to use a custom ExceptionSerializer.  This Knoldus blog post explains it well: https://blog.knoldus.com/2018/02/05/exception-serializer-in-lagom/ That example, however, is more focused on how ...
    • Should Kafka act as the source of truth in Lagom?

      > We are using Lagom with event sourcing and CQRS. Would you say that keeping the source of truth on the Kafka side is an option? Pragmatism always wins the day, and with that being said this idea has plenty of merit. The only concern we have with ...
    • Does Lagom support multitenancy?

      Our suggestion is to not go down this path. Multi-tenancy was very popular back in the time when people used to deploy one single application on a huge application server. In the era of cloud computing, it's much easier to have different deployments, ...
    • Can Lagom errors be handled using Play error handling?

      No, the Play error handler is not invoked from Lagom, because the Lagom exception serializer intercepts it first. Any exception thrown by application code will be wrapped in a transport exception, serialized to json and a response is built from it. ...
    • How to run some Lagom services instead of one or all

      Currently, Lagom’s built-in tooling allows for running a single service via run or all of them via runAll. In some cases you may find it more convenient to run a specific subset of services. The simplest solution for this is to create ...