Meaningful collaboration across the API lifecycle

Kin Lane

October 31, 2022

Today’s enterprise is often made up of many isolated teams that are striving to remain in sync with leadership’s objectives without causing trouble or friction. To accomplish this goal, most API development teams have started to ground their work with machine-readable artifacts that are rooted in specifications like OpenAPI, AsyncAPI, and JSON Schema. While these artifacts assist with documentation and code generation, they often fall short of their full potential to drive collaboration and communication. Additionally, some large organizations still use the waterfall software development model, in which teams are bogged down with meetings and synchronous communication. This approach leads to misalignment among teams, as well as with leadership.

There are several best practices that can help organizations address these pain points—even at enterprise scale. This post will explore five of them in detail.

Move beyond organizational silos

There are many reasons that teams become isolated and disconnected from one another. Sometimes it is intentional, but other times it is the result of legacy processes, organizational shifts, and churn. In an API-first world, in which every team both produces and consumes APIs, it can make sense for teams to exist and operate autonomously—as long as they are able to collaborate in a meaningful way. It is for this reason that API-first teams—especially those that are also remote-first—prioritize well-defined microservices, supporting documentation, reusable code, and machine-readable artifacts. While Amazon CTO Werner Vogels popularized the concept of the “two-pizza team,” or a team small enough to feed with two pizzas, the API-first model is what enabled Amazon to transcend organizational silos with common API authentication, documentation, SDKs, and feedback loops.

Drive collaboration with machine-readable artifacts

There are too many details in an enterprise microservice and API landscape for any human—or team of humans—to keep up with. The highest functioning and most collaborative teams therefore leverage JSON Schema to map out the enormous number of objects in motion, and they rely on OpenAPI and AsyncAPI to define synchronous and asynchronous access to them. Machine-readable artifacts help teams understand the digital resources and capabilities that currently exist at their organization—and allow them to predict what future iterations of these objects and their access will look like. Common API specifications also facilitate better collaboration by enabling teams to establish shared and reusable lifecycle definitions for the thousands of artifacts, resources, and capabilities in their API landscape.

It’s important for teams to realize that OpenAPI, AsyncAPI, and JSON Schema aren’t just for documentation and code generation. They also play an essential role in keeping humans and machines on the same page throughout the API lifecycle, even in the ever-expanding enterprise operational landscape. This allows humans and machines to move at a higher velocity, with more confidence, and without encountering many of the traditional bottlenecks.

Communicate asynchronously

The API-first model emphasizes the importance of integrating Slack, Teams, and other communication tools into existing workflows. This strategy augments how teams are already communicating by bringing machine-readable artifacts into the conversation. For instance, teams can attach a specific API specification, object, or property of a machine-readable document to any communication thread, which can include team members in different time zones.

There are several benefits to this type of asynchronous, artifact-driven communication. First, it is significantly faster than scheduled meetings, which helps remove a common development bottleneck. It also grounds interactions in specific repositories and workspaces, enabling teams to more easily collaborate on the design of an API path or channel, remind one another that a specific header is required, or debate the correct casing for parameters and schema properties. This workflow leaves a historical record of every change—and the conversation around it—which other teams can use to inform their own approach.

Give teams agency

Separating teams by domain, function, geographic region, or other logical bounded context makes a lot of sense—as long as they are properly equipped for success. Leadership should reduce obstacles and friction by ensuring teams have a known workspace and possess the skills and tools they need—and then get out of the way. A team shouldn’t have to think about how they will set up the entire world around them, but they should have the agency to define their own requirements, set their own road maps, and do what they need to do to bring their microservices to life.

It’s important to note that giving teams more agency increases their accountability. Teams with greater agency have greater responsibility to not only support their own consumers, but also optimize their own reliance on other teams as a consumer themselves. Every developer on every team should understand that the relationship between API-first producers and consumers is a two-way street.

Improve operational visibility

It’s important to use repositories and workspaces to lay a common foundation for where teams work. This enables discovery by default—and ensures that teams can collaborate with one another on machine-readable artifacts in an asynchronous and ongoing way. Workspaces support the other best practices discussed in this post and enable organizations to establish communication SLAs for the team-to-team feedback loops that move APIs forward. Workspaces also provide organizations with the necessary operational visibility to more confidently march forward and achieve their business goals.