Microservice & API Versioning

[benle...@gmail.com]

The author of Production Ready Microservices has some serious experience. I was surprised by the following warning in her book, and think it worth considering.

Avoid Versioning Microservices and Endpoints

A microservice is not a library (it is not loaded into memory at compilation-time or during runtime) but an independent software application. Due to the fast-paced nature of microservice development, versioning microservices can easily become an organizational nightmare, with developers on client services pinning specific (outdated, unmaintained) versions of a microservice in their own code. Microservices should be treated as living, changing things, not static releases or libraries. Versioning of API endpoints is another anti-pattern that should be avoided for the same reasons.

[Josh Zamor]

I take it you mean this blurb.  Some more details behind this reasoning would be useful if you get to it.

[benle...@gmail.com]

That’s right; this is what else she writes:

Versioning of internal libraries and/or microservices and pinning to specific versions of internal libraries and/or services is very much discouraged in micro‐ service architecture because it tends to lead to bugs and (in extreme cases) serious failures, because of the fast-paced nature of microservice development: these libraries and services are constantly changing, and pinning to specific versions (along with versioning of these services and libraries in general) can lead to developers using unstable, unreliable, and sometimes unsafe versions of them.

Logging Without Microservice Versioning

Microservice versioning is often discouraged because it can lead to other (client) services pinning to specific versions of a microservice that may not be the best or most updated version of the microservice. Without versioning, determining the state of a microservice when a failure or outage occurred can be difficult, but thorough logging can prevent this from becoming a problem: if the logging is good enough that state of a microservice at the time of an outage can be sufficiently known and understood, the lack of versioning ceases to be a hindrance to quick and effective mitigation and resoution.

My intent with this post isn’t to argue against versioning, but rather to share unexpected advice from a credible book. If I were to argue against versioning, though, I’d add that:

* Supporting backward compatible APIs necessarily leads to more complicated, difficult to maintain, code.

* The traditional approach to versioning APIs is often to also strive to limit breaking changes. I’ve even seen people argue against ever making such changes. It’s easy to imagine this stunting the growth of an API and its associated product.

* Although microservices provide modularization just like traditionally versioned libraries, there are some important differences. Libraries, in the most general sense, are often:

A) Downloaded and compiled into a monolith, which is then stuck with that version of the library, bugs and all, until the monolith is manually upgraded.

B) Used by numerous, unrelated, projects.

Given this distribution and usage model, versioning libraries makes perfect sense. The extent to which microservices are used to offer modularity exclusively within a single application, however, is the degree to which traditional assumptions about the need for versioning can be revisited.

[Josh Zamor]

A lot of your points are well taken, Ben.  I’d ask though:  is the current distribution model of OpenLMISv3 so different from a library?  We currently release open-source software that’s versioned on a regular schedule.  Realizing the vision of shared benefit, we plan on many of those pieces being recombined, launched and even extended in independent runtime-environments that are not controlled by OpenLMIS (i.e. if country X was being launched, they could do so on their own hardware/cloud and have some choice in what they launched and how the pieces were recombined).  In this way our usage of micro-services feels atypical compared to many organizational usages such as Uber or Amazon.  This is why we version the Services, modules, and so on as well as the final Reference Distribution.

If more of our stakeholders desire a SaaS model, then the more that I can see this changing.  Ben, if you come across an open source project that has similar modularity for shared benefit goals, please do post it to this group.

--
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev...@googlegroups.com.
To post to this group, send email to openlm...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/3de3f0ab-8fe2-4ced-b41b-5caf7fdd1366%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Darius Jazayeri]

This is a very interesting conversation.

The entire model of OpenLMIS v3 as flexible and extensible is based on the idea that country implementations will need to fork and/or add their own services. So it's important that we do publish documented versions of the core services for them to build against. (They are like libraries in this sense.)

At the same time, we won't have the central resources to maintain multiple versions of each service. So realistically we should be pushing country implementations to regularly upgrade as part of their standard process, and if they don't, and need to pin to specific service versions, then they need to be responsible for backporting bugfixes and security patches themselves.

Basically:

• do release versioned services (and use semantic versioning)
• don't commit to long-term maintenance of each service; set the expectation that individual services can/will evolve in future OpenLMIS releases (and this will be communicated by semantic versioning of the individual services)

-Darius

To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev+unsubscribe@googlegroups.com.

To post to this group, send email to openlm...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/3de3f0ab-8fe2-4ced-b41b-5caf7fdd1366%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.

To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev+unsubscribe@googlegroups.com.

To post to this group, send email to openlm...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/8AED803D-7AB4-42E4-80AA-F30B7CAA7B86%40villagereach.org.

For more options, visit https://groups.google.com/d/optout.

--

Darius JazayeriPrincipal Architect - Global Health

Email

djaz...@thoughtworks.com

Telephone

+1 617 383 9369

[Josh Zamor]

+1

Thanks for the reminder Darius.  When we kicked off the re-architecture this point of keeping the community and implementations following along (or be at the mercy of providing their own support) felt very salient considering the funding nature of the project and the goal of shared benefit for the community.

We’ll need to keep reminding ourselves and our stakeholders, especially as we get ready to launch the first production release, spin off a parallel team to support the Malawi implementation and work towards the next dot release that there are no long term support releases.

-Josh