Building great APIs is about so much more than just writing code. As companies begin researching and thinking about how to build an API program, the resources they are most likely to encounter are platforms and toolkits that help them build successful APIs — but often, those resources don’t spell out how to get started from an organizational standpoint.
I think this is why one of the most common questions I get from business leaders and developers new to APIs is something like: “These tools are great, but how do we get started?”
While I’m not a fan of formulaic approaches or one-size-fits-all playbooks, there are definitely some proven fundamental principles that tend to work at any scale.
Here are four essential API components to launching any successful API program. They include some common trends we’ve looked at on the API Intersection Podcast that I host, which focuses on helping API leaders scale their API programs.
Universal, Customer-Centric Vocabulary
Organizations that intend to transition to platform thinking and/or transformation must first define a consistent way of describing what they do, expressed in APIs. One of the biggest factors that determine the usability of the product is a shared vocabulary that makes sense to the end users, regardless of whether or not the product is an API.
The entire exercise boils down to answering this question: What are all the things for our customers, and what is one word to describe each of them?
If that sounds like a tall order, companies can get off to a solid start by distilling a simple, customer-centric explanation of their platform.
Reaching consensus on this foundational definition will significantly improve teams’ understanding of customers and will set the tone for how to approach defining a new vocabulary that prioritizes customer or end-user needs.
An often-referenced method to derive this language is known as business capability modeling, which is typically preferred over the more complex and developer-friendly domain-driven design (DDD) approach (although, if DDD is already working for you, you’re ahead of the game).
Approaches based on business capability modeling use customer-centric language as often as possible to describe the functions of the organization. This helps ensure that these design efforts are inclusive for business personas as well as customer advocates (e.g. support, developer relations, etc.) who might not understand (and shouldn’t need to) existing assumptions derived from system architecture. Business-oriented terms are more inclusive and engaging for stakeholders who don’t have development backgrounds.
This approach opens the door to the functional organizational design technique known as the Inverse Conway Maneuver. As ThoughtWorks describes the technique, the Inverse Conway Maneuver “recommends evolving your team and organizational structure to promote your desired architecture. Ideally, your technology architecture will display isomorphism with your business architecture.”
The business capabilities view of the organization provides a window to the future, and it can be mapped to the existing organizational structure to affect a unified ROI model across business and technology. The shared language between business and API development forms a bridge, and that bridge is built on the simple language of “What are all the big things?”
Once the business capabilities are defined, the last step is to describe the relationships between the capabilities so customers can gain a clearer understanding of how all the pieces come together.
At this stage, workshops are an effective and engaging way to get teams and stakeholders all working together. While there are a number of ways to facilitate a workshop, there are a few keys to making the most of them.
First, it’s important that attendees are diverse and inclusive beyond the product development organization. However, choose leaders who are thought leaders around platforms and APIs in their respective organizations. Bring together a mix of subject matter experts on business, tech, and customers for the imagined domain; sometimes members may need to change as alignment evolves.
The workshop should focus on the “big things” and key business and customer impacts, rather than implementation details and technical minutia, as those topics will not be accessible to all attendees. If a good portion of the attendees can’t relate to the topics being covered, these events can quickly become stalled or unproductive. Worse, focusing too much on implementation often takes the focus off of customers and end users for the APIs.
The ultimate goal of developing and consistently using a customer-centric vocabulary is to translate capabilities and vocabulary into API designs, customer communications, and potentially even ROI measurement that appeals to end users, rather than programmers and developers.
Companies don’t need to overthink this step. It’s all about getting the right people in the room and determining what the most important points are and how they relate to each other. If a company can do that, it can likely build great APIs.
For a practical example of what this looks like in practice, see the multi-part blog from my former colleagues at PayPal on InfoQ, “Untangling an API-First Transformation at Scale”.
Style Guides with Automation
You shouldn’t create an API program to make a bunch of APIs; you should stand up an API program to produce a consistent, unified customer experience across brands and platforms.
The consistent use of design elements and conventions is the primary aspect that makes a bunch of APIs feel like a unified platform, and an organization’s style guide is central to this effort.
A good style guide documents a company’s API style in one place that everyone can refer to, and a great style guide automates rules and validation to the greatest extent possible.
Style guides minimize complexity for API consumers by ensuring the consistent use of design conventions. Numerous teams can use those same style guides to deliver APIs that feel like one cohesive system when viewed together. A platform of consistent APIs creates an environment of innovation for consumers who want to deliver value faster than building it themselves.
You don’t even need to create a brand-new style guide. You can adopt one — there are numerous open-source resources available. API Style Book, for example, offers an extensive collection of published style guides. Stoplight’s Spectral tool, an automated open-source linter, helps companies go a step further to edit and create style guides. When you automate most of your style guide with a tool like Spectral, API reviews typically become much more about substance than form.
For large organizations with multiple working API teams, automated style guides are crucial to maintaining brand consistency.
Decentralized Governance
Every organization needs some type of API review process, and there are two approaches to consider: centralized and decentralized.
While the idea of completely centralized API review teams can be appealing from a controls perspective, these “center of excellence” teams almost always create bottlenecks by slowing down the process and reducing engagement with other contributors. A more nuanced, enablement-focused approach is often the most productive.
Under a decentralized enablement model, the API team focuses on education, capacity-building within maker teams, and curating standards for the broader organization. It’s more of a consulting and evangelism role and less of a top-down organization — and it’s proving to be a much more effective approach. The enablement team basically helps contributors look good and be successful in designing great APIs.
Rather than simply implementing and enforcing API standards, a decentralized API team focuses on building an API program that works and is user-friendly, so people will choose to use it because it makes the most sense.
These teams also work on building relationships with thought leaders and contributors from each domain or developer group within the company and work to build capabilities enough that each group has the ability and autonomy to complete its own API reviews over time.
A Mechanism for Early Feedback
Tactile feedback results in faster innovation, and the earlier in the process that good feedback can be acquired, the better.
Interdisciplinary engagement and collaboration are key to this step, to make sure both the development team and non-technical contributors are all on the same page. At the very least, a nontechnical description of the API’s functionality should be shared with all contributors as soon as the API specification exists.
While documentation and discussion are a good starting point, providing mock APIs will allow API consumers to really try it out and find issues faster, and also enable parallel development of the API while consumers build their end.
In general, API teams should parallelize the development and consumption of APIs, to make sure the end product tracks closely to the end user’s expectations. Stoplight’s Prism tool, which is an open-source mocking and contract testing tool, allows for collaboration and coordination between developers and API teams. This partnership helps facilitate an efficient design process while avoiding costly delays due to end users or developers not understanding how projects would come together.
Culture Change Is at the Heart of Transformation
Platform transformations are challenging because of the cultural changes they require, not the technologies involved.
True transformations only happen when there is a fundamental shift in perception that is often counterintuitive to people within the organization. They must transition from focusing on internal vocabulary and syntax (think acronyms and org charts) to the external audience — customers and API end users.
It’s a profound shift, and it can get messy when companies don’t successfully transition and try to build an API program with a “business as usual” mindset.
The bottom line is that there are simply no substitutes for deep stakeholder relationships and collaboration. In most cases, companies building APIs will have to change the way people work together to be successful.
I’m the CTO of Stoplight, and I’ll be blogging about APIs and how we’re helping countless companies establish productive API programs. I hope you’ll join the conversation.
