Business Roles

The first group of roles we’ll review are the ones we call business roles. The people who take on these roles are primarily focused on the business side of the APIs. They often have the responsibility of speaking in the customer’s voice, aligning the product with clear strategic goals (e.g., promoting new products, improving sell-through, etc.), and matching APIs with company-wide OKRs. Sometimes the people fulfilling these roles will come from the business or product parts of your company. Other times, they will come from within the IT ranks. The important difference between these roles and the technical roles we’ll cover next is that business roles focus first on business objectives.

We’ve defined five business roles to represent the decision-making responsibilities we see in healthy API programs:

API product manager

The product manager (PM)—sometimes called the product owner—is the main point of contact for the API. This is in keeping with the API-as-a-Product (AaaP) approach we covered in Chapter 3. They are responsible for making sure the API has clear OKRs and KPIs and that the other members of the team are in place to support the needed API pillars (Chapter 4). The PM is also responsible for monitoring the API and shepherding it successfully through the full API lifecycle (Chapter 6). The API PM role is in charge of defining and describing to the rest of the team the what of the API (or jobs-to-be-done). It will be the technical roles on the team that will be responsible for the how. PMs are also responsible for ensuring the expected developer experience (design, onboarding, and ongoing relationship) meets the needs of the API consumers. The PM’s role is to make sure all the moving parts come together as expected.

API designer

The API designer is responsible for all aspects of the design. This includes making sure the physical interface is functional, usable, and offers a positive experience for developers. The designer also needs to make sure the API helps the team to achieve the identified business OKRs. In some cases, the designer will work with the technical roles to make sure the design helps the team meet the technical KPIs, too. Often the designer is the first line of contact for API consumers and may be responsible for taking on the “voice of the consumer” when helping the team make decisions about the look and feel of the API. Finally, the designer may be called upon to make sure the overall design matches established company-wide style guidelines.

API technical writer

The API tech writer is responsible for writing the API documentation for all stakeholders connected with the API product. This includes not just the API consumers (e.g., the developers using the end product) but also the internal team members as well as other stakeholders from the business community (e.g., the CIO, CTO, etc.). Most tech writers will come from a technical background and have some programming experience, but this is not always the case, nor is it always required. It is important for tech writers to be effective communicators as well as effective researchers and interviewers, since they often need to understand the point of view of both the API providers and the API consumers. For this reason, tech writers often work closely with the API designer and product manager to make sure the documentation is accurate, up to date, and in keeping with the company’s design and style guidelines.

API evangelist

The API evangelist is responsible for promoting and supporting the API practice and culture within the company. This is especially true in large organizations where internal users do not have easy access to the original API team that created the product. Evangelists make sure all internal developers using the API understand it and can accomplish their goals with it. Evangelists are also responsible for listening to API consumers and passing their feedback on to the rest of the product team. In some cases, evangelists may be responsible for creating samples, demos, training materials, and other support activities in order to maximize the developer experience for those using the product.

Developer relations

The developer relations role, sometimes called the developer advocate or DevRel role, is usually focused on external use of the API (i.e., outside the company that created it). Like the API evangelists, DevRel staff are responsible for creating samples, demos, training materials, and other assets to help promote the use of the product. And like evangelists, DevRels are often the ones responsible for listening to API consumers and helping turn their feedback into fixes or features that the API team can deal with. However, unlike internal evangelists, DevRels are also often tasked with “selling” the API product to a wider audience, and as such may participate in customer onsites, presales activities, and ongoing product support for key customers. Additional duties can include speaking at public events, writing blog posts or articles on how to use the product, as well as other brand-awareness activities in order to help the team reach their stated business goals.

While these five roles are often aligned with business goals and strategies, as you can see from the descriptions, most of the roles still rely on some level of technical knowledge and skill in order to meet their objectives. The next set of roles we’ll review are focused directly on the technical aspects of creating, deploying, and maintaining the API product.

Technical Roles

The second set of roles we defined are what we call technical roles. These roles are focused on the technical details of actually implementing the API’s design, testing and deploying it, and maintaining it in a healthy, usable state throughout its active life. Typically these roles are responsible for speaking in the voice of the IT department, including advocating for safe, scalable, and secure implementations that can be properly maintained over time. Often, the technical staff are responsible for achieving important KPIs as well as helping the business staff reach their OKRs.

Even though we’ve divided our list of roles into two distinct groups, there are some parallels between the business roles and the technical roles. For example, the business role of product manager has a parallel in the lead API engineer on the technical side. And both groups of API roles have, as their ultimate goal, the creation and deployment of a technically stable and economically viable API product.

We’ve defined six technical roles to represent the key decision making involved in the work of implementing, deploying, and maintaining successful APIs:

Lead API engineer

The lead API engineer is the key point of contact for all the work related to the development, testing, monitoring, and deployment of the API product. This role is the technical equivalent of the product manager business role. Just as the PM is responsible for the what of the API—the design and business goals—the API lead engineer is responsible for the how of the API—the technical details of what it takes to build, deploy, and maintain the API. The lead engineer is the one with the responsibility to coordinate the other technical members of the team.

API architect

The API architect is responsible for the architectural design details for the API product itself as well as making sure that the API can easily interact with required system resources, including APIs from other teams. It is the responsibility of the API architect to advocate for the overall software and system architecture of the entire organization. This includes supporting the security considerations, stability and reliability metrics, protocol and format selections, and other so-called nonfunctional elements that have been established for the company’s software systems.

Frontend developer

The frontend API developer (FE) is responsible for making sure the API offers a quality consumer experience. That means helping to implement the company’s API registry, consumer portal, and any other activities related to the frontend or consumer end of the API. Similar to the designer role on the business side, the FE has the job of advocating for API consumers, but from the technical point of view.

Backend developer

The backend developer (BE) is reponsible for the details of implementing the actual interface of the API, connecting it to any other services it needs to complete its work, and generally faithfully executing on the vision of the PM and API designer’s description of what the API should do and how it should do it. It is the responsibility of the BE to make sure the API is reliable, stable, and consistent once it is placed into production.

Test/QA engineer

The API test/QA (quality assurance) engineer is responsible for everything related to validating the API design and testing its functionality, safety, and stability. Typically the test/QA role is charged with writing (or helping the FE/BE write) the actual tests and making sure they run effectively and efficiently. Often this testing goes beyond simple bench tests and behavior testing and includes making sure there are tests for interoperability, scalability, security, and capacity. Typically this involves the use of testing frameworks and tooling selected by the test/QA community within the company.

DevOps engineer

The DevOps role is responsible for every aspect of the building and deployment of the API. This includes monitoring the API’s performance to make sure it is in line with the stated technical KPIs and is properly contributing to the business-level OKRs. This usually means working the delivery pipeline tooling, authoring build scripts (or teaching others how to do this), managing the release schedule, archiving the build artifacts, and supporting any rollbacks of broken releases, if needed. The DevOps role is also responsible for maintaining a dashboard showing real-time monitoring data as well as storing and, when needed, mining offline API logs to aid in the review, diagnosis, and repair of any problems identified while the API is in production. Depending on the company’s production hosting options, DevOps staffs will need to support several environments, including desktop, build, test, staging, and production. This may include both on-premise and cloud systems.

In this section, we introduced the idea of thinking about the work to be done over the life of your API as a set of roles, or scopes, of responsibility. To make things a bit easier for our discussion, we came up with two sets of roles (business and technical) and gave these roles names that look like typical job titles.

As we mentioned at the start of this section, the roles are just that—they identify areas of expertise that need to be covered within your API programs. We’ll look at this aspect of team composition next.

Teams and API Maturity

In each stage of the API product lifecycle, some roles play a primary role and some play only a secondary or supporting role. Primary roles are the ones that make the biggest impact with their decisions. For example, in the create stage, almost everyone on the team has important responsibilities, but the designer’s decisions about the interface design strongly influence all of the other work.

Primary roles are also the ones responsible for the work that must be done in an API. For example, in the publish stage, the API can’t be deployed unless someone takes on the DevOps role and builds a deployment architecture.

As you can see, team population is greatly affected by the API’s maturity and the roles needed at any one time. With that in mind, let’s go through the API lifecycle stages from Chapter 6 and identify the primary and secondary roles in each, along with the types of activities that each of these roles will be responsible for.

Scaling Up Your Teams

Understanding that roles are the essential building blocks of teams and that team composition requirements are affected by the maturity stage of the API product is just the start of the challenges of governing API teams. Another big element is dealing with many teams. Often each API has a team, but there is more than one API. Working in a community of teams (a team of teams?) brings a whole new level of complication.

It is a good idea to treat each API team as an independent group—that means they can solve their own problems with minimal dependencies on other teams. But reality is not quite the same as theory. Theoretically, teams don’t need each other. Actually, teams can’t work well without each other! So how does that work? There is a constant push/pull between maintaining independence and working well with others. It is important to build more than a single team strategy. It is also important to have a larger view of how the various parts (teams) fit together as a whole.

In his book Team of Teams (Portfolio), General Stanley McChrystal talks about a different way of thinking about how large organizations succeed: “As the world grows faster and more interdependent, we need to figure out ways to scale the fluidity of teams across entire organizations.” That means understanding how to get teams to work together without forcing them to become dependent upon each other.

One organization that has built a reputation for being able to scale up its team system is the digital music company Spotify. Spotify’s 2012 whitepaper on the topic is an often-quoted reference to thinking about ways to improve the effectiveness of both individual teams and cross-team communications. Even though the paper is a bit dated (six years is a long time in Internet terms!), we find many other organizations using similar approaches to those outlined in that Spotify paper—so much so that we think it is still valuable to understand the key lessons from Spotify and explore how you can apply them in your company.

Teams and Roles at Spotify

In 2012, Agile coaches Henrik Kniberg and Anders Ivarsson published the paper “Scaling Agile @ Spotify”. Its opening line acknowledges, “Dealing with multiple teams in a product development organization is always a challenge!” Kniberg and Ivarsson then go on to explain how Spotify designed its team management model to help maximize information sharing without jeopardizing team independence. This model (or some variation of it) is now something we see at many companies.

The Spotify team model has four key elements or groupings:

• Squad

• Tribe

• Chapter

• Guild

Squads are small, self-contained teams of five to seven members, similar to a Scrum team. They are the basic unit of work at Spotify. A squad has all the skills needed to do its assigned work, from design to deployment, just like the teams we’ve been talking about here. At Spotify, each squad has a mission or job within a larger product group. For example, for the Android music player, one squad might “own” the playback experience, another might own the search experience, and so forth. The squads get the work done.

At Spotify, the tribe represents a larger product scope, such as the aforementioned Android music player, or the website, or the backend storage service used by all other client products. In this way tribes are collections of squads. At Spotify, they try to keep the total number of people in a tribe to around 100. This is considered large enough that there is enough diversity in the group to get things done, but not so large that it gets too hard to maintain healthy relationships.

With squads and tribes, Spotify is able to build an effective strategy for creating and maintaining its products and services. However, that’s only one half of the challenge. It is also important to enable some level of efficiency in this community. That means some kind of inter-squad and inter-team communication to share knowledge and ensure consistency across teams and products—and that’s where Spotify’s chapters and guilds come into play.

Since each team is self-contained, each team is likely to have a designer, or backend developer, product manager, etc. Each person fulfilling these roles has their own challenges and learning experiences. However, often these experiences are similar to those of others in the same role on other teams. For example, what it takes to be a good product manager for a squad in the Infrastructure tribe is a set of skills all product managers share, even if their exact approaches are not the same. It therefore makes sense for product managers in the same tribe to get together once in a while and share their experiences and knowledge with each other. At Spotify this is what a chapter is about—people with the same roles within a single tribe (e.g., the same product group) getting together and sharing knowledge.

Guilds, on the other hand, are a way to share knowledge across multiple product groups at Spotify. For example, getting some of the product managers from all areas of the company together (from customer-facing products to internal-facing systems) offers an additional level of knowledge sharing. In your company, a guild might represent a collection of team leaders from across the globe who get together once a year to share what they are working on in their various divisions.

At Spotify, the model of squads, tribes, chapters, and guilds provides the right mix of self-contained teams without creating isolated groups of people who don’t talk to each other. This is their way of balancing independence with cooperation.

Scaling Your Teams on Paper

The Spotify approach to scaling teams represents a decentralized point of view. Scaling is built into the working model itself. Another way we see companies scaling their teams is by employing a central team designed to collect information from all the other teams and share it through whitepapers, standards documents, and best practice training.¹

In this way, it’s possible to scale up knowledge sharing without requiring face-to-face meetups or internal conferences. This method is particularly effective for very large organizations where teams are scattered across the globe and in different time zones, making even virtual meetings complicated.

However, it is not a good idea to rely only on shared documentation and pretaped presentations for sharing experience and knowledge across the company. In-person training, sharing, and collaborating is always more effective and often more efficient than just reading an article or watching a video.

And that leads us to the last section of this chapter, which is about company culture. The way team members work together and the way teams collaborate with each other is greatly influenced by the culture and values that already exist within an organization. For that reason, it is important to invest time in learning about and crafting your own company’s culture.

Recognizing Conway’s Law

In the last several years, Mel Conway’s 1967 paper “How Do Committees Invent?” has become an almost required topic in presentations about microservices as well as APIs in general. This paper is the source of what Fred Brooks dubbed “Conway’s law” in his 1975 book Mythical Man Month (Addison-Wesley). Conway’s law states that:

Organizations which design systems…are constrained to produce designs which are copies of the communication structures of these organizations.

This “law” is an observation about how the way groups are organized affects the output they produce. An often-cited supporting observation comes from Eric S. Raymond, author of The Cathedral & the Bazaar (O’Reilly), who states: “If you have four groups working on a compiler, you’ll get a 4-pass compiler.” Boiled down to its essence, Conway’s law tells us that, when it comes to producing working software, the organziational boundaries you have will determine the applications you get. This is both good and bad news.

As we mentioned at the start of this chapter, the software we write is “dumb”—it does only (and precisely) what humans tell it to do. Conway reminds us that the way we arrange people into groups—where we place the boundaries between teams—determines the results. For this reason some IT consultants talk about implementing a “reverse Conway.” They encourage setting up your teams and boundaries first in order to get the results you want. This can work to some extent, but has its own problems. In the same 1967 paper Conway warns us about getting too aggressive with our organizational scalpels:

[Conway’s Law] creates problems because the need to communicate at any time depends on the system in effect at that time. Because the design which occurs first is almost never the best possible, the prevailing system may need to change. Therefore, flexibility of organization is important to effective design.

Essentially, you can’t “out-Conway” Conway’s law! There is a trade-off here. It’s important to point out that the notion of organizational structure is key to influencing company culture. Companies that seem to do well in managing culture have at least two things in common: they work to make boundaries both clear and, flexible over time.

It is fine to establish clear boundaries between teams early in the project. This helps sort out responsibilities within teams and delineate interfaces between teams. However, it is also important to keep Conway’s warning in mind: “the design which occurs first is almost never the best possible” Therefore, as you move forward with your API and component projects, it is important to adjust boundaries based on real-world discoveries. This is a normal part of the work.

Just like so many other aspects of the API management space, managing the culture is continuous. Conway gives us hints on what we can do to effect change (e.g., focus on the boundaries between teams) and warns us that our first attempts are rarely the best possible option (“the prevailing system may need to change”). That leads to questions about how teams and team size can affect the corporate culture. And this leads us to the work of Robin Dunbar.

Leveraging Dunbar’s Numbers

Conway tells us about how teams and boundaries affect the output of any endeavor. So, a logical question is what makes up a team and, more directly, what is an optimal team size. Many of the customers we work with rely on the 1990s research of Dr. Robin Dunbar for the answer. In popular social science writings, his theories on how the brain affects group size are best known through what’s called Dunbar’s number, which posits that we can successfully keep track of and maintain useful relationships with, at maximum, about 150 people. Any group larger than that taxes most brains’ abilities to lead and manage the group. Essentially, once the group grows past this number, keeping the members coordinated, on-task, and working together gets much tougher.

There are many confirmations of the power of 150 when it comes to communicating with groups. William “Bill” Gore, founder and chairman of the W. L. Gore company from 1970 to 1986, established a rule that once a single factory contained more than 150 people, the group should be split up and a new building built (sometimes right next to the existing one). Netflix’s Patty McCord calls this the “stand-on-a-chair” number: once you get past 150, a team leader can’t easily just stand on a chair to address the entire group.

While Dunbar’s 150 is an important number, our experience tells us the research behind that number is more valuable. Dunbar’s theory is that we need to spend time and energy to successfully communicate in groups and that group size affects the amount of effort needed to maintain successful connections. In fact, his early research determined that teams of 150 “would require as much as 42% of the total time budget to be devoted to social grooming.” In other words, as teams grow larger, more time needs to be devoted (by everyone) to maintaining group cohesion. In the modern office setting “social grooming” takes the form of meetings, emails, phone calls, instant messaging, daily stand-ups, shift meetings, and so forth. Large teams are costly when it comes to coordination.

The good news is, Dunbar has more than just one number. He actually identifies a series of numbers starting with 5, 15, 50, 150, and on up into the 1,000s. At the lower end of the scale (e.g., 5 and 15), the coordination cost—social grooming—is very small. In a team of five, everyone knows each other well, everyone knows their job, and—most likely—everyone knows who, if anyone, is not pulling their weight in the group. The social grooming time is quite minimal. Even at group sizes up to 15, the comminication cost is relatively low. You may notice that the team sizes we recommended earlier in this book hover around the 5-person mark (give or take 2 or 3).

This small (five- to seven-person) team is what we call a Dunbar Level One team. It is the size most common for early startups. Dunbar Level Two teams of up to 15 people are often found in young companies that have gotten past their first angel funding rounds and are actively building the business. Many of the IT organizations we talk to work to keep their team sizes at Dunbar Level One and Two in order to minimize communication costs and maximize the effectiveness of the teams in general. Spotify, for example, aims for “squads” of about five to seven people each (see “Teams and Roles at Spotify”).

Dunbar shows us that team size matters and that communications within smaller teams can be more efficient. Conway reminds us that the interconnection between teams determines the ultimate output. The challenge, then, in crafting a successful API management culture is shepherding lots of teams inside a large organzation. Just as working with a landscape of APIs presents different challenges to working with a single or a small set of APIs, there are unique aspects to confront when you are working with a landscape of teams. Some of the work of physical architect Christopher Alexander can help with this “team of teams” challenge.

Enabling Alexander’s Cultural Mosaic

Leading and/or supporting a single team is not an easy task. Getting a group up and running, helping them find their footing and style and learn to be positive contributors to the company mission, is hard (but rewarding) work. Those who do this kind of work often also know that every team is unique. Each team has to travel through the same general landscape in its own way. The variations from team to team are key to building diversity and strength into your company. Even though it might seem that you’d want all teams to look and act the same way, that is not a sign of a healthy ecosystem.

This “landscape of teams” presents the same kinds of challenges and opportunities as a landscape of APIs (see Chapter 8), and many of the same landscape aspects we outline in that chapter apply to the landscape of teams too. As you grow your API enterprise, you’ll be dealing with more variety, volume, volatility, and other elements of a healthy ecosystem. In fact, human systems (e.g., teams) typically become better as variety is introduced. Most of us have experienced cases where adding a new “outsider” to our teams has resulted in a stronger team. There are all sorts of aphorisms along these lines, including “What doesn’t kill you makes you stronger”—the notion that unexpected challenges can help us get better. Nassim Taleb’s 2012 book Antifragile (Random House) is based on this very premise.

Another point of view on the power of “teams of teams” can be found in the writings of the physical architect and thinker Christopher Alexander. His 1977 book A Pattern Language (Oxford University Press)—the book credited with launching the patterns movement in software—includes the concept of a “mosaic of subcultures” as a way to organize communities in a healthy, sustainable way.

Alexander’s “mosaic of subcultures pattern” idea describes three essential ways to deal with large collections of people and the smaller groups that emerge within the whole. Alexander’s writing is applied to city-sized collections, but in our experience it has important parallels for IT leadership dealing with global and enterprise-level organizations.

Alexander outlines three approaches to how subgroups appear within large communities (his point of view being the city itself):

Heterogenous

People are mixed together irrespective of their lifestyle or culture, reducing all lifestyles to a common denominator that turns out to be homogeneous and dull.

Ghetto

People cluster along their most basic and banal forms of differentiation, race and/or economic status, creating isolated groups which are still homogeneous within each ghetto.

Mosaic

A number of small areas with clear boundaries of separation form, between which people can freely move in order to experience the lifestyles and cultures that interest and inspire them.

It may take a bit of effort to get past Alexander’s city-planning domain, but our experience is that these notions of widespread homogeneity (“We all use the same tools and processes throughout the company”) vs. ghettos (“We’re all data engineers here; the QA people are in the other building”) vs. mosaics (“I joined this group because I wanted to work on our mobile app”) are prevalent in IT organizations, too. Every company has its own shared cultural elements, and subcultures that grow up within that organization. Being aware of these subelements of culture is the first step toward dealing with them and, in most cases, leveraging them in the mission of growing a healthy and resilient API management culture.

We’ve made the case here that it is not enough to just understand the dynamics of communication within a single team (e.g., Dunbar). We’ve also highlighted the power of inter-team connections, as described by Mel Conway. Finally, we introduced the notion of a “landscape of teams” and the importance of paying close attention to the way in which teams are formed (e.g., Alexander) and the ecosystem in which they operate. But what is the payoff here? Why spend time on these elements of culture, especially with regard to managing APIs?

It is your company culture that determines the level of innovation, experimentation, and creativity that teams and individuals can exercise. Your culture is the key to success when growing your company.

We’ll touch on this last aspect of culture next.

Supporting Experimentation

One important reason for spending time grooming a company’s culture is to help foster innovation and transformation of the organization’s day-to-day operations. A big reason for this is expressed in a quote attributed to business management guru Peter Drucker: “Culture eats strategy for breakfast.”

Essentially, no matter your strategy, it is the prevailing culture that drives the company. Therefore, if you want to change the direction of your team, your product group, or even the entire organization, it is culture on which you need to focus. This is the message that Conway teaches us, as well: it is the organization and its boundaries that establish the output of the group.

A key to fostering innovation—the creation of new products, methods, and ideas—is the ability to experiment safely. Experimenting doesn’t mean launching some half-thought-through idea into production. Like so many other things we’ve talked about in this book, experimenting starts small (e.g., within a team) and goes through repeated rounds of iteration to learn from, winnow down, and identify related ideas in order to find something valuable, useful, and desirable; something that might be worth spending precious time and resources on in order to bring to life.

In his 2006 book Direct from Dell (HarperCollins), businessman and philanthropist Michael Dell puts it like this: “To encourage people to innovate more, you have to make it safe for them to fail.” The key point here is that failure should be not just easy or common, but safe. Teams should be placed in an atmosphere that allows them ample room to experiment, but constrains them from making costly mistakes that disrupt important company operations. One way to create this kind of ecosystem is to use the decision elements we outlined earlier in this book (see “The Elements of a Decision”). When teams know their boundaries, they have a clearer sense of what kinds of experiments they can use in order to learn how to improve.

Another big part of supporting experimentation is understanding that lots of teams running experiments is better than a few teams (or just one team). In “The Center for Enablement” we discuss the power of having a dedicated team, one that can help establish guidance and guardrails for the enterprise. This is not, however, the place where all the experiments happen. Just as in other aspects of IT, heavy centralization and concentration can lead to increased vulnerability and volatility. On the other hand, distributing activities across a wide range of teams and product groups improves the chances of successfully generating valuable ideas and reduces the likelihood of those experiments causing the company real damage along the way.

This last point might be counterintuitive for some IT leaders. It might follow that more experiments adds to volatility, but this is only true if all the experiments are happening in a single place—for example, in a Center for Enablement (C4E) or some other experimentation hub. This concentration of risk is discussed by Nassim Taleb in his book Skin in the Game (Random House). Author of Black Swan, Antifragile, and other best-selling books, Taleb reminds his readers, “the probabilities of success from the collection of people does not apply to [one person].” Put directly, an ensemble of 100 teams making experiments with new APIs is not the same as one team making 100 experiments in a row. You can use your knowledge of the decision elements to reduce risk while you increase experimentation.

And increasing experimentation means more attempts at innovation, which leads to a continuous API management model (see “The API Product Lifecycle”) that can more easily be sustained over time.

To make this all work at a level that is both sustainable and economical (but not necessarily efficient) you need a diverse community of teams working on projects that drive their passions. And that is where Alexander’s moasic comes into play.