The Power of Team APIs: Streamlining Cross-Team Interactions
Software modules communicate with each other. Be it via APIs, event-driven mechanisms, or even shared storage. As software developers, we became aware that explicitly defining and documenting these communication channels is essential for the maintainability and long-term evolvability of the system.
If the system has a sufficient size, those software modules are likely not maintained by one single team. Usually, multiple teams work together and often separate their areas of responsibility by allocating specific modules to certain teams. The structure of the software system and the communication structure between the development teams mirror each other, as I have elaborated in “The Homomorphic Force: When Software and Team Structures Reinforce Each Other”.
In that article, I also discussed how carefully crafting explicit cross-team communication channels along with technical communication plays a crucial role in aligning teams to the system’s structure:
If you have decoupled development teams, make sure to decouple the modules themselves as well. Use technical patterns like asynchronous communication, independently deployable services, and decentralized data storage. Use communication patterns to decouple teams. Co-locate teams that need to work tighter together and actively separate teams that don’t. Make sure that only the communication channels that are necessary due to product dependencies are the ones being actively used. Not all communication is good; what we want is focused communication between specific teams.
However, as we have many tools to describe technical cross-module communication (like OpenAPI or EventCatalog), we barely have any tools to describe social cross-team communication. A few years back, while reading the book Team Topologies, I discovered Team APIs - a tool that helps us make those social communication channels more explicit.
What is a Team API?
By formulating a Team API, development teams can publish typical and deliberately designed interaction points for other teams. It contains everything about the team that other teams need to know to contact it and provides context to make interactions more productive. Usually, this means
describing what the team's responsibility is: what modules or features are they responsible for?
answering whether the team provides value to end-users or development teams (e.g. as a platform or enabling team)
listing what the team provides for other teams. This could be technical concerns like an API or social aspects such as consulting.
stating how to reach the team
describing what the team is currently working on and what other teams it relies on to achieve its goals.
The following figure shows an example of a Team API for a hypothetical development team at a music streaming service. It is based on the "Team API Template".
Conclusion
Defining technical communication explicitly is crucial. Social communication lacks the same methodological profoundness and toolchain. Team APIs are an effective solution to make team responsibility and cross-team communication more transparent and explicit.