Microservice API Evolution in Practice: A Study on Strategies and Challenges

TL;DR

The paper tackles the challenge of evolving microservice APIs in loosely coupled systems by conducting 17 semi-structured interviews across 11 companies and applying grounded theory. It identifies six practical strategies for REST and event-driven API evolution, along with six corresponding challenges, revealing two core problems: tight organizational coupling and consumer lock-in. The study highlights the roles of backward compatibility, versioning, and cross-team collaboration, and suggests automating change impact analysis and improving change communication as open research directions. The findings offer concrete, practitioner-focused guidance and emphasize the need for tooling and processes to support sustainable API evolution in microservice architectures.

Abstract

Nowadays, many companies design and develop their software systems as a set of loosely coupled microservices that communicate via their Application Programming Interfaces (APIs). While the loose coupling improves maintainability, scalability, and fault tolerance, it poses new challenges to the API evolution process. Related works identified communication and integration as major API evolution challenges but did not provide the underlying reasons and research directions to mitigate them. In this paper, we aim to identify microservice API evolution strategies and challenges in practice and gain a broader perspective of their relationships. We conducted 17 semi-structured interviews with developers, architects, and managers in 11 companies and analyzed the interviews with open coding used in grounded theory. In total, we identified six strategies and six challenges for REpresentational State Transfer (REST) and event-driven communication via message brokers. The strategies mainly focus on API backward compatibility, versioning, and close collaboration between teams. The challenges include change impact analysis efforts, ineffective communication of changes, and consumer reliance on outdated versions, leading to API design degradation. We defined two important problems in microservice API evolution resulting from the challenges and their coping strategies: tight organizational coupling and consumer lock-in. To mitigate these two problems, we propose automating the change impact analysis and investigating effective communication of changes as open research directions.

Figures (2)

• Figure 1: Proportion of communication techniques of the total communication among interview participants.
• Figure 2: The relationships for a subset of strategies (light grey) and challenges (dark grey) resulting in two problems (dashed).