Team APIs

What is a Team API?

In Manuel Pais and Matthew Skelton’s book Team Topologies: Organizing Business and Technology Teams for Fast Flow, they mention a concept which can potentially be quite powerful for Agile teams in general – the “Team API.”

Here is how Pais & Skelton define it:

With stable, long-lived teams that own specific bits of the software systems, we can begin to build a stable team API: an API surrounding each team. An API (Application Programming Interface) is a description and a specification for how to interact programmatically with software, so we extend this idea to entire interactions with the team.

Note: We’re using the term “API” differently from in the conventional, technical sense (Application Programming Interface).  Here we’re using the term to signify that we can create patterns for the ways in which a team communicates, outside of code, both internally and externally. For instance, we can do this by setting up a team space in Confluence, which has a particular structure, which makes it easier to find information about what the team is working on, and similar topics.

What’s the Benefit?

The primary benefit of a Team API, for multiple teams that work together or need things from one another, is analogous to the benefit of having a Team Working Agreement for a single team. A single team can benefit from writing down their thoughts on how they can best collaborate. A team API makes it easier for teams to collaborate, because they have a certain set of pattern-driven expectations about where to find information about what the other teams are doing. 


Agreeing to a Team API can be helpful in many situations, such as the following:

  • Starting up one or more new teams
  • Re-baselining expectations across an existing set of teams

Who Attends?

  • A facilitator (often a Scrum Master or an Agile Coach)
  • All of the team members 


  • Awareness of where team technical artifacts are located
  • Awareness of where to find a summary of what the team is working on
  • Awareness of where to find information about how the team currently works


  • “Just enough” documentation for other teams to know where to find the information they need (see below for examples)

What Can a Team API Include?

Simply stated, a Team API can include:

  • Information that is likely to be beneficial to the team itself (internally facing)
  • Information that is likely to be beneficial to other teams and to stakeholders (externally facing)

In other words, the Team API consists of “just enough” documentation to describe the why, what, and how associated with the work that the team does. The choice of the word “can” in the sentence above is important, because we want to avoid being overly prescriptive (giving teams flexibility in terms of the level of detail), while at the same time identifying a baseline set of expectations in terms of topics that each Team API ideally covers. That is, we want the Information Architecture (content structure) that the team uses, in Confluence for example, to be reasonably consistent from one team to the next, to make it easier for teams to “consume” the information from each other.

Do All of the Artifacts That the Team API References Have To Live in a Tool Like Confluence?

The short answer to this question is “no.” It is perfectly fine to provide links to code repositories, Swagger documentation, and so on. An important consideration is having some level of consistency when it comes to where in the Team API hierarchy these types of links to artifacts can be found.

Preparing for Success

  • If the facilitator is new to the Team API concept, self-study will be necessary
  • As noted above, a session where a Team API is created or updated will be more successful if there is awareness of where to find artifacts and other information


Keeping in mind that the areas needing coverage could vary, depending on team context, below is a list of topics that potentially can be included in a Team API. Thus, to prepare for a session where a Team API is to be created, it will be necessary to know where these types of things are located:

  • Code: Endpoints, libraries, clients, UI, data stores, etc. produced by the team
  • Versioning: How the team communicates changes to its code and services (e.g., using semantic versioning (SemVer) as a “team promise” not to break things)
  • Documentation: Examples of helpful documentation can include:
    • How-to guides associated with the software owned by the team
    • Team Calendar
    • Team Members
    • Team Mission, Business Objectives
    • Team Roadmap
  • Dependencies: Information about dependencies the team has (in either direction – dependencies they have on others, or dependencies others have on them)
  • Practices and principles: The team’s preferred way of working. Note that the “preferred way of working” can include things like:
    • Definition of Done
    • Definition of Ready
    • Team Working Agreement
  • Work information:
    • What the team is working on now
    • What’s coming up next for the team

Additional Considerations for Team APIs

Pais and Skelton provide the following additional observations about Team APIs:

The Team API should explicitly consider usability by other teams: Will other teams find it easy and straightforward to interact with us, or will it be difficult and confusing? How easy will it be for a new team to get on board with our code and working practices? How do we respond to pull requests and other suggestions from other teams? Is our team backlog and product roadmap easily visible and understandable by other teams?

For effective team-first ownership of software, teams need to continuously define, advertise, test, and evolve their Team API to ensure that it is fit for purpose for the consumers of that API: other teams.