Architecting Teams: Designing your team API

Every software engineer should be familiar with their team's API. Their team's API is what other teams will use to interface with them when designing and building solutions. It is their boundary of responsibility and it is the first line of defence against scope creep. In this post, we'll discuss why it's so important to define your team's API and how to go about doing it.

Why You Need a Team API

A well-defined team API serves a number of purposes. First, it provides a clear boundary of responsibility for your team. Other teams know exactly what they can and cannot call on your team for. This prevents scope creep and keeps everyone on the same page. Second, a team API provides a consistent interface for how other teams should interact with your team. This means that there are fewer surprises and fewer opportunities for things to get lost in a backlog or ignored entirely. Finally, a team API makes it easier to onboard new members of your team because they have a clear starting point and a clear understanding of what their responsibilities are.

How to Define Your Team API

There are a few things you need to keep in mind when defining your team API. First, you need to think about what other teams will need to interface with yours to do their jobs. What information will they need? What specialist skills will they need? Who will they need to talk to? Second, you need to think about how often other teams will need your team. If it is only occasionally, then you can get away with a simpler API. However, if other teams will be relying on your team daily (Platform/Infrastructure teams I'm talking to you), then you need to make sure that your API is robust and easy to use. For example, a simple Design System teams "API" might be something like this;

"We are responsible for the creation and maintenance of components within the design-system repository. We are responsible for fixing problems within the components themselves, but we are not responsible for debugging and fixing issues by integrating them into the solutions of other teams. If you have a feature request or would like to report a bug, please raise a ticket following the process outlined in this document <Rasing a feature/bug request>. Any requests sent directly to engineers will not be actioned, and you will be referred to the above process. For any P0 requests as defined in our SLAs (<Design System SLAs>), please raise a ticket using the above process and escalate it to <Team Leader> in the public team channel".

For a more in-depth API I recommend doing the following steps;

1. Define the Problem

The first step is to sit down with your team and identify the areas where there is confusion or ambiguity about roles and responsibilities. What are the questions that people are constantly asking each other? What processes are taking longer than they should because people don't know who is responsible for what? Answering these questions will help you to identify the areas where your team's API needs to be better defined.

2. Draft the Solution

Once you've identified the areas that need work, it's time to start drafting the solution. This will involve creating a set of expectations for each role on the team. What are the core responsibilities of each role? What are the boundaries of each role? What is off-limits for each role? Answering these questions will help you to create a clear and concise definition of each role on the team. You can then uplift these responsibilities into your team API, and provide a guide on SLAs for different types of requests. Be careful not to expose who will handle each request type, especially if there is only 1 person (you might have a skills problem if that's the case), as you don't want people to bypass your process and go straight to engineers. Then you can't keep track of how much ad-hoc non-project work your team gets asked to handle.

3. Implement the Solution

The last step is to implement the solution. This will involve communicating the new expectations to all team members and making sure that everyone is on board with the new way of doing things. It may also involve making some changes to processes and procedures so that everyone is working within the new boundaries that have been defined. Once everyone is on board, it's time to start reaping the benefits of having a well-defined team API by shouting about it to the wider engineering organisation and giving your team the autonomy to ignore requests that do not follow the agreed processes.

Conclusion

Defining your team's API is one of the most important things you can do as an engineering leader. It sets the boundary of responsibility for your team and provides a consistent interface for other teams to use when interacting with yours. When defining your team API, make sure to think about what other teams will need and how often they will need it. And finally, make sure to talk to your team about what they need too.