How to handle API dependencies in a microservice architecture

How to handle API dependencies in a microservice architecture

As presented in one of my previous blogs, microservice architecture is an increasingly more popular architecture in modern software development. The concept of creating minor applications, which can be containerized, deployed, and scaled single-handedly has some obvious advantages.

However, as we all know software changes over time. More features are added, and bugs are fixed causing the code within one or more applications to change. Some of these code changes might also cause API changes. In this blog I am going to elaborate on technics and possible strategies for maintaining a functional microservice architecture regardless of changes to the applications and their APIs

Master Microservice Deployment With Docker-Compose

Docker & Docker-Compose Tutorial

Why is API changing a problem?

Firstly, I want to clarify what I mean by the term “API” in this context. By API, I refer to the interfaces between the individual microservice applications.

Previously when working with monolithic applications, we only had to manage our external API interfaces, since there wasn’t any within the application. However, with the microservice architecture, it is quite normal to have more API interfaces internally than externally. Taking full advantage of microservice concept also means creating small single domain applications. Having many internal APIs also means that the internal applications have a dependency to each other.

How to handle the API dependency?

Internal API dependency handling works just like externally. Therefore, my proposed methods might not come as big news to other developers. However, the same methods might have different implementation, given the API are only used internally.

In the following section I am going to present multiple method of maintaining the API dependency:

  • Shared API object projects
  • Semantic version
  • Compatibility checking

Shared API object projects

When working with APIs we are intending to send a piece of information from one service to another. However, for this to be successful we need to know that both services have the same expectation for the format of the information. This can be achieved by using shared API object projects.

A shared API object project is a separate project from the services, written in a common standard, which can be parsed into any of the microservice’s programing language (e.g. JSON Schema). It also requires its own version control management, so that we can ensure that the service projects are using the same version of the API objects to communicate with each other.

INTEGU - Shared API objects project - microservice API dependency

Semantic version

With shared API objects, it is as mentioned important to keep track of the individual services and their respective API version dependency. Multiple services will have the same API dependency. Therefore, we need to know if these dependencies are kept to the same version, or if not that they are still working based on a compatible API version aka. No breaking changes.

To achieve this insight, we follow the semantic versioning pattern. In short, a semantic version is a description of the project’s version separated into three sections: MAJOR. MINOR. PATCH.

  • MAJOR: Version when you make incompatible API changes
  • MINOR: Version when you add functionality in a backwards compatible manner.
  • PATCH: Version when you make backwards compatible bug fixes

Following this versioning pattern will provide insight into the compatibility between each of the individual microservices.

INTEGU - Semantic version - microservice API dependency
INTEGU - Semantic version incompatible - microservice API dependency

Note: When using this type of versioning pattern for the shared API objects, any major version incrementation, will automatically also affect the version of all dependent services. When the service’s API objects have breaking changes, it affects the services in the same way.

INTEGU - Semantic version change - microservice API dependency

Compatibility checking

Through the two previous steps we managed to get a method of tracking API dependencies and determine if the services in the microservice architecture is compatible with each other. Now the issue becomes how to assert this compatibility on a stable and frequent basis.

Given that a microservice architecture will often include many services, and thereby many API dependencies, it is arguably best to automate this task. This could for example be achieved through a CI/CD tool (e.g. TeamCity)

I will avoid going into the specifics of how to create such a build configuration, and instead just cover the basic idea. Essentially the build agent of the CI/CD tool will need to go through each individual microservice project and verify that it is using a compatible API version when compared to all other services.

Recommended Reading

In case that this article caught your attention, I would recommend that you checked out the books “Building Microservices” and “Using Docker” by O’Reilly publication.



Hi, I'm the Author

My name is Daniel H. Jacobsen and I’m a dedicated and highly motivated software developer with a masters engineering degree within the field of ICT. 

I have through many years of constantly learning and adapting to new challenges, gained a well-rounded understanding of what it takes to stay up to date with new technologies, tools and utilities. 

The purpose of this blog is to share both my learnings and knowledge with other likeminded developers as well as illustrating how these topics can be taught in a different and alternative manner.

If you like the idea of that, I would encourage you to sign up for the newsletter.

Cheers! 🍺

Didn't Find What You Were Looking For?

Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors
Scroll to Top
INTEGU - Cookie-consent

INTEGU uses cookies to personalize your experience and provide traceability for affiliate links. By using the website, you agree to these terms and conditions. To learn more see the privacy policy page.