We all know that APIs are the ultimate collaboration technology for the industry, but we don’t talk enough about how APIs are also a great collaboration opportunity for your internal team. Why is collaboration such a key feature of work on APIs? Let’s walk through some API governance examples.
- First, APIs inherently require multi-disciplinary teams in both the creation and maintenance stages. At a minimum, most successful APIs require collaboration between developers and customer-facing teams, such as sales and customer service.
- As well, good APIs are built to last, which means they have to evolve over time. Since no single team member stays in the same place forever, it is critical to have clear standards and documentation in place to enable ongoing collaboration and help with knowledge transfer from past team members to future ones.
- In addition, APIs are—or at least should be—client-agnostic. API solutions that are too closely tailored to a single client’s needs won’t provide value for others and don’t live up to their promise. The goal of an API should be to create reusable solutions that enrich ecosystems and inspire evolution for a variety of clients.
Building excellent APIs requires putting a lot of thought into API creation, a process that almost always involves collaboration. A frequently neglected step, however, is thinking through how your teams should approach that collaboration process.
Fortunately, a variety of existing collaboration models mean you don’t have to reinvent the wheel. By the time you finish reading this article, you should have a better understanding of how to plan for an effective API within your team and possibly an idea of which collaboration model is best for your needs.
Plan Ahead to Avoid the Mess
As in most endeavors, proper planning upfront can save a lot of headaches down the road. So what does that look like when it comes to API platform governance and collaboration?
First, it helps to consider what happens without proper planning— when APIs are created ad hoc. Here are just a few of the problems that can occur:
- Breaking changes. If you aren’t careful, changes can make your APIs unusable for your clients. Microsoft, for example, outlines in their API documentation what they consider to be breaking changes to the LinkedIn API. Sometimes making these kinds of changes is unavoidable, but you never want to make them unintentionally.
- Inconsistent documentation. When different teams use their own processes to create APIs, there’s no guarantee that the results will have a unified feel across the organization. If users need to access APIs created by different teams, inconsistencies in documentation can make it harder for them to get what they’re looking for.
- Conflicting standards. As with inconsistent documentation, conflicting standards can also diminish the developer experience.
- Duplicate endpoints. Ideally, a given source of data should have a single endpoint. Having duplicate endpoints can lead to unexpected behavior when people try to access the same data from different endpoints.
- Unclear protocols for fixes. If the documentation and standards for an API are unclear, it stands to reason that the process for fixing problems is also a bit of a shot in the dark.
How do we avoid these potentially disastrous outcomes? We plan ahead, follow industry best practices, and implement a collaboration and governance process.
Follow Industry Best Practices
Before we delve into different collaboration and governance models, let’s name some best practices for any API creation process:
- Identify your goals at the beginning. If you don’t establish clear goals at the beginning, you have no way of knowing if you’ve achieved them later on. Our Schneider Electric case study explains how clear goals led to a sped-up API creation process and improved reusability.
- Create an inventory of your existing APIs. Before you can go anywhere, it’s important to know where you are. Creating an inventory of your organization’s APIs is also a great opportunity to look for inconsistencies in your API creation process and consider how to fix them. You might also discover forgotten APIs or APIs that only a few team members know about.
- Decide on consistent terminology. In general, a given the word or phrase should have only one meaning in the context of your APIs. If a term has come to have multiple meanings for different teams or APIs, choose one meaning to keep and find alternative terms for other meanings. Conversely, if teams have come to use multiple words or phrases to describe the same concept, select one to standardize on. Rackspace’s documentation guidelines provide some specific examples and solutions for these kinds of terminology problems.
This kind of up-front planning is not merely an academic exercise. Years of building APIs ad hoc can leave an organization with inconsistent and outdated documentation, a frustrating developer experience, and poor user satisfaction.
This Calendly case study outlines challenges Calendly faced and how they overcame them—and built a new API platform—with a design-first approach.
Organize and Empower Your API Collaborators
There’s no single API collaboration and governance model that works for everyone. In this section, we’ll discuss some of the most popular choices:
- A single cross-discipline API team
- A designated API representative on each engineering or product team
- A DevOps-focused governance model
Read on to learn about some of the advantages and disadvantages of these approaches.
Types of Governance Models
Single Cross-Discipline API Team
A cross-discipline API team functions similarly to a product team. For best results, it should include engineers working on backend functionality. This helps ensure that any APIs created integrate well with the codebases being used.
In general, an API team should have a balance between focus on technical solutions and focus on business goals. For further guidance on building an API team, this blog post from Adservio lists types of expertise you might wish to have on your API team. Some of the roles suggested may surprise you!
Designated API Representative
Another approach to governance is to have an API representative on every engineering or product team, plus an API oversight committee. This approach is great for building buy-in to standards, since all API representatives will have the same information. A potential disadvantage of this approach is that, without strong leadership, it can be hard to move changes forward if teams resist their representative’s recommendations.
Also, while this approach ensures that all technical aspects are in coordination, it is possible for the team to get bogged down in procedure and lose focus on the product at hand. For an example of a company that has applied this approach successfully, take a look at this wefox case study.
DevOps-Focused Governance Model
A DevOps-focused approach is automation-centered and is well-suited for deploying changes quickly and smoothly. It does, however, require some DevOps expertise on each engineering team. Fundamental DevOps principles, like continuous integration/continuous deployment (CI/CD), are easy to adapt to API collaboration and governance. Consistency and automation are key principles in both settings.
A potential disadvantage of this approach, however, as with the representative model, is that product focus can sometimes be lost. For an example of applying DevOps methods when creating APIs, see this Microsoft documentation outlining some challenges and benefits.
Common Themes
Regardless of the exact governance model that’s right for your organization, a few common principles support any API collaboration:
- Hands-on technical leadership builds buy-in from team members. It also helps ensure that everyone feels some degree of ownership, which is more likely to yield practical goals that people can agree on. This blog post from Cleo explains the importance of strong leadership in the API creation process.
- Prioritizing the product and the consumer takes more work than people may be accustomed to in this stage of the API creation process. However, this work also yields significant rewards with easier maintenance and fewer problems down the road. For PagerDuty, a more consistent collaboration model helped them bring new features to market more quickly, along with other benefits.
- Automation makes centralized governance much easier to achieve, which can help with efficiency. Design review, testing, and documentation can all be automated to some degree. For more information, our article on API governance includes examples of processes that can be automated, as well as the benefits of doing so.
- APIs should be accessible to engineering teams across the organization whenever possible. Developers are sometimes fond of obscure programming languages with neat features, but as fun as they can be, they can also hamper collaboration. Try to choose languages, frameworks, and tools that are widely understood to make collaboration easier. Our Highmark case study illustrates the benefits of making it easy to reuse assets across an organization.
APIs have been around long enough that simply throwing something together and putting it online doesn’t cut it anymore. Because APIs can be the most frequent or prominent ways that people interact with an organization, it makes sense to think of them as the products they are—and to require the same standards of excellence you would for a tangible product for sale.
Get Started
Now that you’ve learned about some API collaboration and API governance models, you might have a better idea of which one is best for you. Whichever one you choose, you can do so with the confidence that many organizations have used these models successfully and that they are aligned with industry best practices. If you want to take a deep dive into a particular process, why not check out our case study library? You might find a design governance model surprisingly similar to your own.
