The API Roadmap

THE
API ROADMAP
Secrets to API strategy success
from industry leaders.
TABLE OF
CONTENTS
03 Introduction
05 How to Start
10 How to Define Your Business Value
16 Designing Your API
24 Public Release, Adoption, and Consumption
28 Feedback and Developer Experience
34 Finding Success
40 Conclusion
stoplight.com The API Roadmap — 2

01
INTRODUCTION
Jason Harmon, Chief Technology Officer at Stoplight
Over the past year, I’ve interviewed more than 20 of the world’s top API
practitioners. I spoke with people in a variety of industries who created
API programs from the ground up, transformed existing technology into
scalable API solutions, set up API governance and security programs at
their organizations, and provided their expertise to everything from
startups all the way up to Fortune 500 companies.
Why this eBook?

So why did we do this? Why have we interviewed so many API experts on the
API Intersection podcast and published dozens of articles about designing
high-quality APIs on the Stoplight blog over the past year?
We’ve been searching for patterns of success in API programs. Since there
hasn’t been a great place to share expertise from practitioners, we created
that space with this podcast, which gave us a great way to start learning
and sharing with the API community. And boy, is that community growing!
Over 83% of all web traffic currently comes from

some form of API. (Sources: Akamai, Nordic APIs)
And 90% of developers use APIs. (Source: Slashdata)
Not only that, but digital transformation spending is

accelerating and APIs are a key technology component.
(Sources: Apigee, IDC)

This eBook is an answer to the growing pains of the emerging practice
of API & Platform design.
More importantly, this eBook is for you. If you’ve found yourself

charged with developing a new product, or perhaps improving the
elusive Developer Experience, there’s no doubt APIs will be
involved, and that means there’s something for you here.
Use this knowledge to help make decisions for your team or org-
anization as you navigate the growing and changing world of APIs.
These are real, concrete stories of API design and

governance success — and sometimes failure.
You’ll find practical advice on how to build quality APIs

through collaborative design, all with goals like saving
time, getting to market faster, and making your APIs
more consistent, secure, useful, and scalable.
What you’ll learn:

How to get started with a design-first API program
How to define your business value
Tips for designing and governing APIs
Ideas for release, promotion, adoption, and security
How to improve developer experience and use feedback
Ways to measure success
As the CTO at Stoplight, a design-first API tool company,

I’m privileged to have remarkable access to API leaders.
Our main goal is to share knowledge from others and help show
the value of a design-first approach from a variety of perspectives.
With the proper resources, insight, and some luck, you’ll avoid pitfalls
and achieve success as you build a world-class API program.

02
HOW TO START

Why You Should Approach APIs
with a Design-First Mindset
Would you start building a house without a set
of plans? When you’ve seen the software and API
equivalent of many such houses built, it’s obvious
that these projects have been expensive and
time-consuming, and led to less-than-ideal business
outcomes. There is a better way to build APIs:
We call it a design-first approach.
In an API design-first development process, API

architects begin with writing a specification and
engaging stakeholders in the process from the beginning.
The purpose of a design-first process is API products that are
comprehensive, consistent, and understandable by people and machines.
There are numerous reasons to build your

API program with this mindset:
Positive Developer Experience: When a design-first approach

is not followed, the development process can become chaotic
and disorganized. These projects often experience lapses and
disconnects between the developers, security, governance, and
documentation teams. This isn’t so much quality control as it
is trying to reverse engineer poor planning and coordination.
It’s like being brought in as a building inspector for a
house that was built with no blueprints.
As developers go back and test endpoints to iron out problems,

they are often met with unexpected vulnerabilities that have to be
addressed by other contributors. This is a time-consuming process
and it is not a good use of developers’ time or talents.
By taking a design-first approach, the API specs, governance,

design, development, and documentation all start on the same page
and are maintained simultaneously. This built-in coordination
keeps developers focused on developing solutions and prevents them
from being slowed down by weeks or months of clean-up work.

Engineering Efficiency and Cost Savings: There is no need to
reinvent the wheel with every API your organization develops.
When quality components are developed and maintained using a
design-first approach, they can be reused for future APIs.
You only need to build components once.
For many of our customers, this is the most important and

beneficial business outcome of using the Stoplight platform.
Reusable components allow for significant cost savings in
development time and enable new APIs to get to market
faster than ever before.
The synchronized maintenance aspect of Stoplight’s approach

also benefits developers as they can rely on having
predictable, updated, and well-designed API components to
plug into each new project.
Improved API Security: Large development teams are notoriously

hard to coordinate, and it’s difficult to bring in people
midstream and keep everyone on the same page.
By taking a design-first approach, you get all of the key

stakeholders involved from the outset of design to build their
input into the governance of the API. Coordination at this level
throughout the development process will keep your security team
plugged in and will also eliminate the potential for loose API
endpoints to be left exposed and vulnerable to exploitation.
Whether you’re building a house or a suite of APIs, synchronization is

the key — making sure everyone is on the same page, and that their
efforts are tightly coordinated.
“The APIs your organization is developing shouldn’t be a

constant drag. Rather, they should be an engine for growth,
increased revenue, and improved user experiences.”
Steve Rodda, CEO at Stoplight

Three Easy Ways to Start Implementing
Your API Product Strategy
When looking at where to start, it can be overwhelming. With a brand new
API, a fresh team, and mountains to climb, you need easy spots to start.
What helped Ikenna Nwaiwu become a better product manager, a more well-
rounded developer, and craft a stronger API strategy was the following:
01 Regular Reading of Support Tickets: Having user feedback on the

frontlines gives valuable insight into developing your API and how
end-users consume it. Direct feedback exposes you to the pain that
the consumers have and where to put your focus.
02 Building Feedback Loops: Add feedback-gathering loops into your API

development stream as much as possible. Creating that stream between
your consumers, engineers, and business-minded counterparts can keep
everyone on the same page when it comes to handling your API product.
03 Use a Systems-Thinking Approach: Think about the systemic level

factors that could stop a problem from coming up in the first place.
Ask yourself the important questions when you encounter an issue
with your new API program:
How can you make sure issues don’t even come up?
What’s the underlying issue?
What can you change in your product discovery process to make

sure that you don’t even have this problem in the first place?
And when you have an answer, test it out! Testing is one of the
easiest ways to see what resonates and what works with your API.
“When it comes to where to even begin, it starts with

listening. When I first started, one of the things I did was
join stand-ups, observe what the pain points were, and truly
absorb the story. That will tell you where to start.”
Ikenna Nwaiwu, API Product Owner

Getting Your Not-So-Tech-Savvy
Colleagues Involved in APIs
Perhaps you have a few entry level developers on your API team, or you’re
a product leader who needs to know where to begin. Maybe you’re a business
leader who just wants to comprehend the technical knowledge a little bit
more when collaborating with your dev team. Here are the main tips for
colleagues who know absolutely nothing about the world of APIs:
A Foundational Understanding of Key Resources: Learning the

relevant resources in the API space will give you a leg-up in
the industry. Understanding resources like Git and programming
languages like JSON, CSS, or JavaScript at the most basic level
will also help. A basic knowledge of coding is an added bonus.
Learn from Leaders in the Community (like in this eBook!):

Following leaders in the API community is a great way to get
started, understand the trends in the industry, and build
your API network.
Get the Right Toolset: When you’re ready to actually start

designing and developing APIs, you’re going to want the right
toolstack. Design, development, documentation, mocking, linting,
review, the gateway, deployment, adoption, etc. are all a part
of the API lifecycle, and you’ll want tools (like Stoplight)
to support that.
“Whether you’re just getting into development, whether you

have been in development or architecture, and you’re kind of
learning APIs, or if you’re in the business side of things
and you’re really trying to understand what APIs are...
there’s a place for you!”
Brenton House, VP of Digital Evangelism at Software AG

03
HOW TO DEFINE
YOUR BUSINESS
VALUE

How to View Your APIs as Products
An emerging best practice in API circles is to treat APIs like products.
Similar to any other company product, APIs should be viewed as business
assets and not just chunks of codebase. Combined within the context of
business offerings and values, APIs can realize their full value.
James Higginbotham, Executive API Consultant at LaunchAny, shares his tips

for considering APIs as products and making the most out of them.
Here are his four main ways of treating APIs as products:
Adopt an Outside-In Perspective: Adopting an outside-in approach

to designing APIs involves an obsession with the customer.
Put yourself in the shoes of your client and understand their

needs and preferences in order to direct product strategy.
Focusing solely on the technology side is detrimental to the
health of your API.
You need to start by aligning with what’s needed in the market-

place, rather than jumping into the code first. Get an outside
perspective and think more about the needs of your target users.
If you build an API program without considering the needs of

your target audience, it may not live to see the light of day.
Form a Team with a Product Mindset: Assemble a dedicated team

with a product mindset that understands how your business works
to help you design and deliver APIs that drive business value.
A team that treats your integration assets as products can

assist the overall organization in creating a vision for the
success of your API programs. They can look at the big picture,
align with business objectives, and steer the API strategy
roadmap in the right direction.
By centralizing knowledge on how APIs are designed, a more

consistent, customer-centric developer experience is possible.

Get the Vocabulary Right: Being able to define a vocabulary for
a particular area, to unify around the API, will make the program
a lot more consistent and easier for the developers who are
going to be using that API.
You can step outside and get a fresh look at the API documentation
from the perspective of an outside user. If you spend time
reviewing the API just like an actual user, you can discover flaws
and inconsistencies in terminologies that were previously hidden.
Adopt New Tech Incrementally: Just like any other business

product, APIs should continually evolve. This will ensure
they address the emerging consumer needs and take advantage
of new technologies.
Starting small, while getting those essentials in place — and

iterating over them until they begin to make sense for everyone
in the organization — can help avoid introducing unnecessary
complexities into your API program.
For example, if you adopt the modern microservices architecture

without preparing sufficiently to handle it, you could introduce
unnecessary complexities in your codebase and complicate API
governance. Why would you need to build several services, each
with its own unique technology, when having a single monolith
could easily solve your problem?
If you include a product mindset in every discipline of the API lifecycle,

APIs will flourish and maximize return on investment. Treating APIs as
first-class components of your product portfolio, from their initial design
to final deployment and management, will help you reap their rewards.
“Stepping away and thinking about [APIs] from the

outside-in will deliver a more pleasant experience and
help people to integrate with your API easily.”
James Higginbotham, Executive API Consultant at LaunchAny

How to Get the Most Out of Your API
Increased API adoption has brought about a business challenge that needs to
be addressed: how to manage APIs properly. Failure to do so is causing APIs
to collapse under the weight of their own success.
You need a robust strategy to create a more thoughtful API program, manage
the consumption of your APIs, enhance the visibility into all of your APIs,
and monitor and analyze their performance.
Here are ways to manage your APIs to get the most from them:
Practice API Management: You need a robust strategy to manage

the consumption of your APIs, enhance the visibility, create
a more thoughtful API program, as well as monitor and
analyze their performance.
Rather than focusing on the checklist of implementation tasks,

help your team understand the management of the digital product
itself and then ask, “How do APIs play into this?” Think about
managing the API holistically from end-to-end of its lifecycle.
Pick the Right Tool for the Job: It’s important to pick the
right architectural style for your API — whether it’s GraphQL,
REST, or event-driven APIs. Keep in mind, just because there
are new design tools available doesn’t mean you need to
pivot your strategy and jump ship.
Rather than focusing on the latest and greatest, choose

the platform that best fits your use case.
Focus on Ease of Consumption: Developers love APIs that

are simple, described properly, and devoid of jargon. Adding
unnecessary complexities into your APIs will only drive
users to look elsewhere.
Build consistency across your APIs, especially if you have

hundreds or thousands of them. These consistencies will make
your APIs predictable, intuitive, and easy to use.

Expose a Valuable Service: Just because an API experience is great
for a developer doesn’t mean you can use it to build valuable
tools and products. Ask yourself the following questions to make
sure you stay on track:
How will the consumer benefit from this API?
How will they use it?
Will they like the experience?
Will it drive traffic?
Educate Your Stakeholders: With sufficient education and

awareness, you can initiate a cultural shift so IT is considered
an integral aspect of the organization. Create literacy plans for
those in non-technical roles so they feel better connected and
informed of any IT-related projects.
It’s also important to include other stakeholders, apart from

developers, in the API building journey. You can perform mapping
exercises, design exercises, API mocks, or other awareness tasks
to encourage involvement and get feedback.
On a final note, remember that simplicity is king. APIs are, at their core,
a communication mechanism. When we try to overcomplicate that process, we
reduce the value to the end-user. Instead, focus on simplicity from start
to finish and don’t try to boil the ocean!
“As things become digital, we get more and more APIs.

This contributes to complexity, and it becomes more
demanding to manage them well and do the right thing.”
Erik Wilde, API Catalyst at Axway

Demonstrating the ROI of Your API Program
Whether you’re a small startup just getting started or a Fortune 500
like Wells Fargo, knowing how to demonstrate the return-on-investment
(ROI) of your API program is crucial.
When an effective API program cannibalizes other process forms, a team

can safely deprecate archaic channels. Wells Fargo has customers who used
to go through file-based and other retro channels. Now, APIs enable them
to solve their needs, further proving the program’s value.
Use a customer-first mindset to demonstrate ROI and track customer metrics

closely. With billions of calls per year, Wells Fargo’s API team needs to
keep a close eye on tracking activity. They track when a customer interacts
with specific APIs to have visibility into that direct line of business,
and how many times a customer used a different channel versus the API to
understand the incremental gain or the cannibalization of archaic systems.
A deep focus on tracking success is an easy way to show ROI of your program.
Three Key Steps to Show Value:
01 Maintenance and Consistency: Making a good API product is not just

about giving the customer what they want, it’s about implementing,
maintaining, and versioning those products with consistency.
02 Study Customer Behavior: Your API program should revolve around a

customer-centric mindset, and value is proven when your customer
behavior reflects that successful usage.
03 Overtake the Old: If your API program is outpacing other legacy

channels that your consumers previously used, that’s a win!
“Like Apple used to say, if you don’t cannibalize

yourself, somebody else will. So in that sense, it’s
good that our API program is leading the pack.”
Daniel David, Director of Product at Marqeta

(previously Wells Fargo)

04
DESIGNING
YOUR API

How to Build Great APIs
It’s important to understand your organization’s requirements and build
an API approach that works best for your team. The design-first method
advocates for crafting an API contract, or an agreed understanding of how
the API should operate, before creating any code. This leads to a more
efficient API development lifecycle, and better outcomes for API programs.
If your organization is trapped in legacy architecture or back-breaking

code and you want to move to a modern development style, the best way to
go about it is to champion a cultural shift. Don’t be afraid to challenge
the status quo to get your API program off the ground. Instead of trying to
make everyone happy, grab the idea you have and get moving — it’s better to
actualize an idea, whether good or bad, than do nothing at all.
Maximize Developer Talent: Empowering developers to work

together using modern tools ensures that they take advantage
of each other’s skills to produce quality products. Relying
on the old techniques is unsustainable and difficult.
Leverage Community Standards: When designing APIs, be sure

your program is set up to embrace community-driven
standards that are already established.
Develop While You Develop: Empower your developers to

improve their own writing skills — writing lets you
appreciate the idiosyncrasies of programming.
With the right people and the design-first approach, you’ll be able to
crystalize the story of the business value of your program clearly.
“A critical first step is to start by defining the values

and goals in your organization that make a big difference.”
Dilip Krishnan, Engineering Manager at Oracle

Three Tips for Building Quality APIs
that Your End-Users Will Love
A good API is like a LEGO® block — or so says Matthias Biehl, author and
advisor to API-University. When designing your API, the simpler, the better.
Building APIs that end-users will love is key to realizing their full value
and achieving your business goals.
If APIs are designed well, developers will find them easy to integrate into
different use cases and make the most of them.
When developing APIs, here are three things to keep in mind:
Implementing robust authentication measures is a good way to

control the type of users who can access your API. In the early
days of API development, a personal secret key was all we had.
Currently, the introduction of the open authorization (OAuth)
protocol has greatly transformed how users are proving their
identity and gaining permission when accessing APIs.
Building APIs that are easy to use paves the way for their
success. Using jargon, domain-based concepts, or incoherent
descriptions will make your API difficult to understand.
If your exposed product is problematic to consume in these
ways, users will give it a wide berth.
The needs and preferences of your target consumers should be

a priority when building an API. It’s vital to have a team in
your organization with a customer-centric mindset. They’ll
help you put yourself in the shoes of customers and
understand their requirements.
“Basically, you should design your APIs for the

absence of complexity.”
Matthias Biehl, Instructor at API University

Creating Quality, Customer-Centric APIs
So, what are the steps to create quality APIs and ensure that customer-
centricity is absolutely central to the process? The Head of Platforms and
APIs at Greenlight (formerly of Paypal) shares the following four steps:
01 Create a Business Capability Model: An important first step when

designing APIs is to create a business capability model that outlines
all the product capabilities that your organization offers to
customers. Instead of developing an API solely for your internal
or external segment assets, create an API based on your business
capability model and the value it offers to end-users.
02 Establish a Product Development Lifecycle: After defining the business

capability model, the next step is to establish the process of taking
the API from concept to launch. This process is called the API Product
Development Lifecycle (PDLC), and it consists of four stages: define,
design, develop, and deploy.
03 Create Standardization: Establish a set of consistent business

entities; when you capture a construct in your API, you’ll know the
specific business entity to use. Enforce consistency by using tooling
to ensure the same styling pattern is applied in a scalable way across
all APIs. With proper evangelization, you can fuel consistency and
make significant improvements to enhance consumption.
04 Deprecate Cautiously: If customers are integrated with an API that

works and serves their business purposes, making a change is often
costly and not desired, so deprecate cautiously.
“We have an API tooling blueprint that is standardized.

It makes things consistent—whether it’s REST, GraphQL,
events-based, or any other type of API.”
Jayadeba Jena, Head of Platforms & APIs at Greenlight

(previously Paypal)

Six Style Guide Tips to
Level Up Your API Design
Some developers say governance is a dirty word.
We like to call it the “key to consistency.” And

with a majority of businesses seeking consistency
in their API programs, one of the top ways to
achieve this goal is through API style guides.
That’s why Arnaud Lauret, the API Handyman,

is an excellent resource on this topic.
Here are the six major style guide tips that will improve
your developer experience and level up your API design:
Not All Who Design Are Developers: Use case documentation is

essential when working with API designers who don’t have a
developer background. The style guide focus for business-minded
designers shouldn’t be on the rules and rulesets, but on viewing
the style guidelines as recipes. Design APIs like shopping for
a recipe and utilize the guidelines as your shopping list to
understand what components need to be designed.
Make your style guides easy to understand and apply to the real
world because not every designer that stumbles across it will
have a technically-minded background.
Remember the Importance of Discoverability: One common problem

with APIs is duplication of effort. If multiple teams are
developing overlapping functionality, your company may have
simply wasted their investment, and worse, created duplication
of maintenance needs going forward. Make sure that new designs
are rationalized and made available to the rest of the
organization as assurance that teams will connect on overlaps
before investing code time. Sharing the leverage of APIs builds
reusability and overall synergy. If consumers of APIs can’t find
the right thing to use because it’s not discoverable, you might
end up with another source of duplicated effort.

Use Style Guide Automation to Drive Consistency: Automating style
guides (with linting tools like Stoplight Spectral) can quickly
bring visibility to APIs which have design attributes that are
inconsistent with the rest of the platform. By eliminating
discussion about conventions that could be checked automatically,
time is freed up to address bigger design questions than simple
conventions; API reviews happen much faster, mitigating the risk
that the API review process becomes a bottleneck to innovation.
Envision Governance from a Human Perspective: It’s critical to use

empathy when looking at governance from a global perspective and
during an API design review. As the reviewer, you need to take on
the persona of a helping hand, explaining to designers that you
are not there to tell them what they are doing wrong. Instead, you
are there to explain design principles and provide value for how
the API design can be modified or fixed. Based on the designers’
context, discuss their needs and build together.
Apply Your Design Thinking on a Larger Scale: When developing any

kind of system, there is a design component that people often
get wrong: it must be easy to understand. Many people will take a
comprehensible system over a high-performing one any day. If you
can understand how something works and how to replicate it, you’re
more likely to use it and keep using it in the future.
Follow Style Guide Thought Leadership: Podcasts like the

API Intersection, and indeed Arnaud’s own website are excellent
resources for leveling up your API style guides. Follow the
conversations on LinkedIn and Twitter happening every day
to stay up-to-date and inspired.
“There are two ways to do a design review. You can be a jerk,

acting as a gatekeeper and policing all the rules … or you
can do it the right way by showing empathy for the designer.”
Arnaud Lauret (the API Handyman), OpenAPI Evangelist, Postman

How to Maximize Your API Strategy
An effective API design strategy plays a vital role in allowing API
consumers to take advantage of the exposed services and integrate them into
various use cases, ensuring the API realizes its full value. The best way
to maximize your API strategy is to begin with identifying your consumers’
needs. You could be putting the cart before the horse if you start building
an API without considering the wishes of the potential end-users.
Here are two ways you can take a

customer-centered approach to your APIs:
Identify Customer Needs: Designing a great API strategy should

begin with identifying your consumers’ needs. Always go with a
style that best reflects your customers’ preferences because they
are the ones ultimately going to utilize your API. Even at the
design stage, the customer is still the king.
Instill Empathy: Having empathy for the end-user, whether it’s an

internal or public-facing API, is vital for your API strategy’s
well-being. Incorporating human elements in API design is crucial
for the success of your API program. Without enough care and
consideration for the consumer, the API could hit a dead end.
APIs are supposed to be an abstraction of complexity. If there is no

empathy, however, APIs are no longer celebrated as capable of removing
the complexity in developing software. Without compassionate design,
it’s difficult to see through the lens and remove the barriers that
can make an API complicated otherwise.
“If somebody does not mind the human side, the

technology side will eventually have problems.”
Matthew Reinbold, Senior Principal Consultant,

Digital Engagement Lead at Concentrix Catalyst

API Strategy at Scale
We’ve discussed API strategy, but what happens at the enterprise level?
Engineers should be given access and agency to contribute to API

strategy at a team level. Many API endpoints and engineering projects
can overlap, so a significant amount of cross-collaboration needs to
occur across your technology teams. Here’s how to scale:
Create an API Portfolio: What helps to ease that cross-

collaboration is having a portfolio that embodies all product
features and the inventory of API endpoints behind the features
that are powering them. Keep track of all the subteams that are
evolving those endpoints in addition to why and how they interact.
Assess the Situation: You may need to spend some time simply
looking at overlapping teams, what they’re doing, and how long
they take to deliver in order to maximize efficiency wherever
possible on large developer teams.
Align Your Teams: Large organizations are constantly moving. One

team might be doing some work the first half of this year, then
another group might be doing work the second half. It’s essential
to ensure these teams and project timelines are lined up.
This is especially important for organizations that conduct continuous

releases multiple times a day throughout the entire year. Having an
organized understanding of all APIs and launches is the only way to keep
the program running efficiently at scale.
“We have thousands of APIs, so they don’t all follow the same
ruleset in one dimension. We think about ownership. When
you have that many APIs, and we just celebrated our 1024th
engineer, you can see why there’s such a focus on scaling.”
Jon Parise, Lead Architect at Pinterest

05
PUBLIC RELEASE,
ADOPTION, AND
CONSUMPTION

You Made an API, Now Let’s
Talk Adoption Strategy
API adoption happens in three stages: exploration,
integration, and adoption. Measuring adoption rates
by looking at the number of API calls is often the
default, but it’s not a great measure of true
adoption or anticipated growth patterns.
Instead, for assessing adoption, measure

the views of the user base and which
API calls are most valuable. Prioritize
these views and work with a handful of
early customers to determine their needs
and aspirations. Then, use that data to
modify your APIs for your target prospects.
Another thing to watch out for as you monitor

API adoption is what can be considered the most
precarious moment in the cycle: “the Dangerous Delay.” The Dangerous Delay
is the time between when a developer finds your API and integrates your
API. It is the time it takes for your API to change from a curiosity to a
need. During this period, it’s vital to listen to early adopters’ feedback,
implement it, and assess to see if they return for more.
There are two typical bumps in usage over this time. The first bump is
during that initial usage where quick, first-time exploration happens with
your API. During the second bump, usage goes up, testing increases, and
serious development is underway. Then, usage goes back to zero again until
they’re ready to integrate it fully.
“Over the last 15 years of working with APIs, I’ve seen

hundreds of companies launch APIs successfully and never
actually get people to use them.”
Keith Casey, Product Strategy at Ngrok

APIs as a Catalyst for Transformation
Claire Barrett supports mature organizations, helping them accelerate their
API maturity in line with their business and technology strategies. The
root cause that presents as a barrier to API transformational change is
that often the commercial model for setting up long-running teams for many
organizations is quite project-based, myopic, and short-term focused.
When embarking on transformational change via an API strategy,

Claire will often encounter three groups of people:
Elders (Sponsors): Those with commercial responsibility for

customers, products, and partner relationships that deeply
understand customer priorities.
Navigators (Technologists): Those with the tools, technical

responsibilities, roadmap, and the know-how to support the
landscape.
Explorers (Transformers): Those who are trying new methods and

tools and bringing that back to be brought to scale safely by
the rest of the team.
All three have different API opportunities for realizing goals. Aligning key
stakeholders is critical to making those evolutionary steps. It’s a delicate
balance between proper governance and empowerment of your API team.
Measuring transformation performance is equally moving toward that bucket

of transformational metrics while still guarding the original metrics
to see the change. Note, there is no “North Star” metric(s) for tracking
organizational change throughout an API-enabled transformation. The point is
that what you’re monitoring throughout the process may evolve over time.
“We repeatedly see that even though people are sometimes

coming with what sounds like a bit more of a technical
problem, increasingly it’s actually a people problem.”
Claire Barrett, Director of APIsFirst

The Dark and Light Magic of APIs
When your business depends on somebody else’s
API performing properly, being dependable,
and being understandable, the need to
have a direct line to people who can
answer your questions quickly is essential.
The pervasiveness of APIs is equally good

and bad for this reason. They spread so
widely throughout an area and often have
many people involved that it can be hard for
consumers to get the answers they need when
something goes wrong on the consumption side.
Who can your API consumers count on?
01 The Surrounding Community: Focus on

building a solid community foundation
and mutual understanding between developer
and consumer to improve consumption rates. This
community aspect can be the difference between success and failure.
02 Developer Relations Team: Community is immediately amplified by things

like the OpenAPI initiative and a strong developer relations program.
There needs to be an infrastructure relationship between engineering
and a DevRel team, in order to be effective with end users.
03 A Common Framework: Having a common API framework is essential for

others to learn and shape the ecosystem and build a strong end-user
consumer community. A tool like OpenAPI creates the agency needed to
utilize all of the tooling with third-party APIs and makes it easier
for end users trying to integrate your API.
“Know your end users’ needs and pain points well … treat
them as your partners when it comes to API consumption.”
Lorinda Brandon, VP of Engineering at BetterCloud

06
FEEDBACK
AND DEVELOPER
EXPERIENCE

Delivering a Great Developer Experience
About 75% to 90% of the digital transformations within companies fail,
and a main reason for that is poor developer experience, which results in
inefficient integrations. A poorly crafted API program makes it difficult
for developers to realize goals on behalf of their end-users.
Here are the four main ways to deliver a great

developer experience with APIs:
Enforce Good Documentation: An API initiative is only as good as

its provided documentation. If the documentation is bad, it’ll
complicate integration, leading to a poor developer experience.
Implement a Scoring System: A scoring system will help you

gauge the performance of your APIs, especially whether they are
providing the intended value to developers.
Build Standards Early: Invest in developing standards that allow

you to use these new styles smoothly. Inconsistencies across
your API design can leave even the most experienced developers
frustrated, and a perpetual cycle of incorrect assumptions or
failed API calls can dampen developers’ enthusiasm.
Consistency: The importance of consistency in your API ecosystem

cannot be emphasized enough. Building consistency throughout
your APIs will make your exposed services easier to consume
and devoid of complexities.
Developers will go for an API program that they enjoy consuming. Similarly,
by building a rich experience, you can empower them to create useful
digital experiences and applications that end-users enjoy using.
“Optimizing the developer experience throughout the

lifecycle of your API is essential for its success.”
Steve Sfartz, Principal API Architect at Cisco

Developer Experience and Style Guides
from the Ground-Up
At SPS Commerce, when it came time to drive adoption of their API program,
they focused on a strong developer experience. They did this through
collaboration and proper processes (such as Style Guide implementation).
It was a collaborative effort over a cross-functional

group of engineers, working together to define
style guides that are both appropriate and
adoptable. Companies looking to do the same
should continue to evangelize and disseminate
information of design reviews while building
out style guide processes. This reduces those
day-to-day cycles, making a better quality
of life for developers.
One problem with developer experience is

that any event can change the way they
think of your product, so it’s essential
to be mindful of every component of their
interaction. Be sure and start with defining
the most important capabilities where you
will see the most gain and build from there
to encompass every single event.
To keep collaboration and developer experience in mind, take a holistic

approach, asking questions like: ‘is this API even the right thing to build?
Should we be augmenting or changing a different API?’ Finally, don’t forget
to get the right people involved, at the right time, with the correct
resources in place. Minding the developer experience from the ground-up
is a sure-fire way to create a winning API program.
“What we’re pursuing really isn’t a technology problem at

all. It never is. It’s a people and process problem.”
Travis Gosselin, Principal Software Engineer at SPS Commerce

Tips to Optimize Your API Design Review
When optimizing the design review process, utilize a design-first,
high-collaboration approach. Your API design review should not be done in
a vacuum. Rather, it should include a variety of opinions from people in
different positions.
We spoke with Aleksei Akimov, Head of API Platform at Monite, about his
tips for optimizing your API design review process.
Automate and Streamline the Review Process: Utilizing a tool

such as automated style guides to sift out the manual work then
leaves room for discussion on more important innovation topics,
such as how customer-centric your API currently is.
During the review process, have a special group made up of

experts with developer experience and other people from different
parts of the organization who know what integration looks like.
Be mindful of how changes to APIs on one side of the
organization can affect others.
Get the Docs Right: Remember that usually people come to

you to try out your APIs, not because they love reading your
documentation, but because they need to solve a specific task.
Ensure your documentation writers are involved early in the
process for every product, empower them with the right tools, and
help them to keep their technical skills sharp.
Greatly understand API lifecycle management and the role the API design
review plays, not only on the outside but also to the inside of an
organization. This will give you insights to enable people to work together.
“I always look at API design as a mixture of technology,

people and culture. We design our APIs to fit the expectations
and experiences of developers who are using this API.”
Aleksei Akimov, Head of API Platform at Monite

Developing an Enterprise-Level
API Strategy: Where to Put Your Focus
Despite the rapid proliferation of APIs, most companies fail to implement a
robust API strategy roadmap. This failure causes them to miss out on value
they originally envisioned for their API programs. Here are five steps to
realize the full value of your APIs:
01 Implement proper API product management: This is necessary to

manage, maintain, implement, test, and version APIs at scale.
02 Enforce an API design guide to promote governance: The style guide

should be a living document — improvements should be made to it over
time as new design patterns are integrated into the API initiative.
03 Automation is good, but not everything needs automation: For example,

the naming of API resources to be intuitive doesn’t need automation.
04 Build around business capabilities to make your APIs consumable:

Segment your APIs based on what they do for customers, designing each
for its capacity to successfully carry out a unique business function.
05 Cultivate a strong developer relations program: Your first developer

community is inside your company. If you can’t get that part right,
you are unlikely to succeed with external audiences.
With a clear roadmap that outlines the objectives of the program, you can
realize full business value. Without a well-defined strategy, your API may
not live to see the light of day. Set up a cumulative plan of actions that
will help you bring the value out of your API.
“If I had a fresh start to our API program, I’d invest

significantly more in communications to internal key
stakeholders regarding the business value of APIs and
the operational imperatives to the program’s success.”
Sophie Rutard, Group Head of Data and API Convenience

at Allianz Trade

Three Steps to Creating a Successful
Developer Relations Program
Developer Relations (DevRel) involves fostering mutually beneficial
relationships with API consumers, acting as a conduit between them and the
organization, and advocating for their best interests.
Despite its growing importance, DevRel is often treated as an afterthought

in most companies. Many don’t know how to execute the program properly —
leaving DevRel to prove their value and return on investment.
Jeff Schneider, Lead Developer Advocate at Asana, dives into some vital
lessons he learned about creating a successful Developer Relations program.
Evangelization: Before external evangelization, run through

internal evangelization to ensure those within the organization
are excited about the API. If you can’t ignite excitement
internally, it will be difficult to do so externally. Show your
internal teams the possibilities of the API and how external
customers are valuably integrating with it to boost morale.
Delegate Out: Developer Relations is not a one-person job.

Depending on your organization’s business model and how the
API fits into it, you can have different sub-teams within the
developer relations department. Each advocacy band should
have well-defined roles and responsibilities as well as clear
communication structures between teams.
Empathize: Analyzing developers’ viewpoints can reveal things

you didn’t know about your API. By listening and empathizing with
them, you can better understand their needs and identify any
missing details in your product.
“The most important thing would be to sit down and

listen to developers or watch them interact with the
API because they’ll give all the answers.”
Jeff Schneider, Developer Advocate, Program Lead at Asana

07
FINDING
SUCCESS

eBay’s Tips to Success: a Blameless
Culture & Good Governance
As one of the first companies to heavily utilize APIs, eBay’s success story
is one that fascinates many in the API community. Tanya Vlahovic, Head of
the Developer Ecosystem & Lead API Architect at eBay, tells us that good
governance and practicing a blameless culture are two of the main things
eBay’s API team focuses on for success.
Good Governance: Practicing good governance ensures that every API

created should fit that technical version, and the process should
be transparent and objective. Good organizations with a strong
governance program actually create a technical vision for the API,
including crosscutting concerns, vocabulary, and consistency. In
practice, good governance can mitigate the challenges that stem
from trying to follow best practices.
A Blameless Culture: As for the ‘blameless culture’ tip, eBay’s

API success is due to this culture that stems beyond just DevOps.
Tanya encourages her team to innovate on behalf of customers and
enjoys the flexibility and risks that come with it. She advises
arming your developers with reasonable technical support to have
forums and multiple points of communication to tap into. Fostering
a blameless culture is a strategic part of eBay’s foundational
success so that their team members feel safe to innovate and
experiment and leaving ample room for cross-team collaboration.
Keep iterating, keep innovating, keep changing, keep listening to the field,
and keep evolving, but realize in order to do that, you need a team of
people who will support that endeavor and create a space for innovation.
“Just because you release your APIs doesn’t mean they are
done. Enable your team to continue to innovate and grow
with the business and take feedback from users seriously.”
Tanya Vlahovic, Head of the Developer Ecosystem and

Lead API Architect at eBay

Navigating the Digital Transformation
Frontier with APIs
The wave of APIs taking over the world manifests not only in new companies
springing up that are absolutely reliant on APIs, but also in transforming
industries that have been around for centuries. The entire automotive indus-
try is transforming into an industry ultimately driven by the API ecosystem.
For tech companies pioneering into that digital revolution, here’s what’s
needed to guide a new wave of developers through the API frontier:
Build a Multidisciplinary API Team: Build an inclusive team of

technical and non-technical stakeholders to see your API across
the finish line. Be careful to avoid duplication of efforts and
stay focused on where to put that investment as your teams grow.
Gain executive buy-in for your API program: Constant iteration

and innovation combined with proven numbers are vital for gaining
executive buy-in. Even if you only have minimal data at first,
take results up the chain and show constant improvement over time.
Transform with your core pillars in mind: Leading with a

design-first approach helps grow your developer team to design
APIs that can be quickly built on, expanded, or updated as the
needs of your end-users change or grow.
Innovate for the future, not just for today: Think about building
for a scaling program that can adapt, grow, and flourish with new
technologies, integrations, and partners down the line.
“Cars are awesome, but they’re definitely different when

it comes to how you’re going to turn these things into
essentially digital phones. APIs are a huge part of
getting that transformation right.”
John Musser, Director of Data and Analytics

for Ford Autonomous Vehicles at Ford Motor Company

The Intersection of Technology,
Education, and Impact
We are entering the era of the API Economy, with the last few years of
innovation being heavily catalyzed through APIs. While there is no doubt
that the API industry is growing like crazy, you need to drive
home the importance of doing your API strategy correctly.
This means designing APIs with a diverse team and creating

inclusion at the forefront of your strategy. Developers
of new technologies like APIs often don’t always have
a diversity of experience that reflects the ultimate
audience of people who will consume that technology.
Forming a strategy of belonging means creating

your organization to be reflective of the com-
munity you serve. Having a strategy backed by
belonging is no longer just “the right thing
to do.” It’s now a huge driver of sustainable
competitive advantage, not just for hiring
quality talent in tech but also for encouraging
people to use your technology and stick with it.
Shared values are right up there alongside there
with the actual technology that you’re delivering.
The most successful DevOps teams have a breadth and

depth of diverse people involved in the API design process, including
various non-technical roles that are involved in the API strategy, and they
lead with a design-first approach. With APIs, we can empower people in both
technical roles, but also non-technical stakeholders as well.
“40% of large organizations today have 250 or more APIs.

I see APIs very much as that hub we need to make technology
and development opportunities available for more people.”
Sally Eaves, Emergent Technology CTO & Advisor

Four Essential Ingredients for a
Successful API Program
And finally, don’t create an API program for the sake of making a bunch of
APIs. Building great APIs is about so much more than just writing code.
You should stand up a program to produce a consistent, unified customer

experience across platforms. One of the most common questions folks new
to APIs ask is: “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 components to launching any

successful API program:
Universal, Customer-Centric Vocabulary: 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 the product is an API.
What are all the things for your customers, and what is one
word to describe each of them? If that sounds like a tall
order, you can start by distilling a simple, customer-centric
explanation of their platform.
Reaching consensus on this foundational definition will

significantly improve your teams’ understanding of customers
and will set the tone for how to approach defining a new
vocabulary that prioritizes customer or end-user needs.
Style Guides with Automation: 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.

Decentralized Governance: 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. Rather than simply implementing and enforcing API
standards, a decentralized API team focuses on building an API
program that works and is user-friendly.
A Mechanism for Early Feedback: Tactile feedback results in faster

innovation. Interdisciplinary engagement and collaboration are
key in this to ensure both the development team and non-technical
contributors are all on the same page.
At the very least, a non-technical description of the API’s

functionality should be shared with all contributors as soon
as the API specification exists.
Culture change is at the heart of any 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.
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. 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.
“It can be a steep climb to build a new API program from

scratch or reign in one that has become unwieldy, but
the business value of a functional and productive
design-first API program cannot be overstated.”
Jason Harmon, CTO of Stoplight

08
CONCLUSION
Jason Harmon, Chief Technology Officer at Stoplight
At the end of almost every episode of API Intersection, I ask the question:
“What would you do first if you had to start your API program over again?”
While there have been some industry-specific answers, the advice has
come down to a few main recurring points.
Don’t boil the ocean.

This is our number one takeaway. If you remember one thing from this
eBook, remember that API change is not about tools, processes, or
technology, and it can’t all happen at once. APIs are about culture
change. If you want to adopt solid, design-first practices and use
APIs to build a comprehensive platform, it requires a shift in culture
and business, one step at a time. It requires teamwork, collaboration,
thoughtfulness, planning, and empathy.
Find the right internal and external partners.

You need to bring together people across your company who understand the
business value of your API program and can help you move forward with it.
Truly understand the customer problems the API is solving, across a
variety of stakeholders. This is the key to understanding how to create
reusability in your API capabilities.
“Next time, I would be less tech-deterministic and look more at the

business and organizational side of it. The sooner we involve those who
think about where and how value gets created and the structures to make
things actually work, the better.” —Erik Wilde

Improve communication across the board.
Speak the same language. Eliminate internal jargon and acronyms,
in favor of simple terms that customers would understand. Help
bridge the communication gap between technical and non-technical
stakeholders by visualizing API designs and using an API
specification like OpenAPI as a focal point.
“Invest significantly more in both internal and external

communications — communications to internal key stakeholders (CIO,
Market Mgmt, Sales) regarding the business value; win stakeholders
over as promoters much earlier in the process.” —Sophie Rutard
Treat APIs as products.

Regularly talk with your customers and partners about what they want
from your APIs. Relying on an internal engineering perspective will
nearly guarantee an “engineered experience”.
Release new versions of your APIs over time with new features and
improvements based on customer feedback.
“If you include an API-as-a-product mindset in every discipline

of the API lifecycle, APIs will flourish and maximize return
on investment.” —James Higginbotham
Take an API Design-First approach.

Describe your API designs in an iterative way that both humans and
computers can understand (using a specification language like OpenAPI)
before you write any code. With this approach, every team speaks the
same language, and every tool they use leverages the same API design.
“The purpose of a design-first process is API products that

are comprehensive, consistent, and understandable by people
and machines.” —Steve Rodda

Provide teams with the right tools.
Ensure consistency across all of your APIs by having your developers follow
the same design rules, best practices, and standards. To achieve that,
developers need the right tools. Focus on API-specific tooling, as modern
platforms often use a variety of software stacks, languages, etc.
“Tooling matters. Next time I’d spend more time thinking about how to
help our teams and scale that help. For example, when we have guidelines,
I’d make sure that we automate checking these as soon as possible so
that it’s easier and less painful for teams to comply.” —Erik Wilde
Spread education and build capacity across

the organization.
Make sure to plan on evolving a decentralized method of governing how
APIs are created and maintained. Overly centralized governance will
eventually create organizational bottlenecks, and it really isn’t the
way you set up a modern organization.
Focus on capability-driven APIs.

Ensure that your APIs represent the digital capabilities for your internal
developers, external users, and partners in order to achieve the desired
outcomes of your end-users and developers. Avoid APIs that use internal
systems as their description.
Did you find this eBook helpful? If you could

start your API program over again, what would you
do differently? Share your thoughts with us on
Twitter or check out the API Intersection podcast.

Stoplight can
help you create a
successful API program.
Stoplight provides a wide range of tools and resources

created to make your API program designs successful.
For example, with Stoplight Studio, you can collaborate

on API designs, taking an API design-first approach
and implementing effective API governance. You can
improve the quality of your API descriptions with
our open-source tool, Spectral, to ensure
consistency across your APIs.
Additionally, with our open-source tool, Prism, you can

create mock servers from OpenAPI documents, validating
and iterating on your APIs before writing any code.
Go to stoplight.io to learn more and

explore the platform for free.

The API Roadmap

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

The API Roadmap

Uploaded by

Copyright:

Available Formats

THE

10 How to Define Your Business Value

16 Designing Your API

24 Public Release, Adoption, and Consumption

28 Feedback and Developer Experience

stoplight.com The API Roadmap — 2

Why this eBook?

Over 83% of all web traffic currently comes from

And 90% of developers use APIs. (Source: Slashdata)

Not only that, but digital transformation spending is

stoplight.com The API Roadmap — 3

More importantly, this eBook is for you. If you’ve found yourself

These are real, concrete stories of API design and

You’ll find practical advice on how to build quality APIs

What you’ll learn:

How to define your business value

Tips for designing and governing APIs

Ideas for release, promotion, adoption, and security

How to improve developer experience and use feedback

Ways to measure success

As the CTO at Stoplight, a design-first API tool company,

stoplight.com The API Roadmap — 4

stoplight.com The API Roadmap — 5

In an API design-first development process, API

There are numerous reasons to build your

Positive Developer Experience: When a design-first approach

As developers go back and test endpoints to iron out problems,

By taking a design-first approach, the API specs, governance,

stoplight.com The API Roadmap — 6

For many of our customers, this is the most important and

The synchronized maintenance aspect of Stoplight’s approach

Improved API Security: Large development teams are notoriously

By taking a design-first approach, you get all of the key

Whether you’re building a house or a suite of APIs, synchronization is

“The APIs your organization is developing shouldn’t be a

Steve Rodda, CEO at Stoplight

stoplight.com The API Roadmap — 7

01 Regular Reading of Support Tickets: Having user feedback on the

02 Building Feedback Loops: Add feedback-gathering loops into your API

03 Use a Systems-Thinking Approach: Think about the systemic level

What’s the underlying issue?

What can you change in your product discovery process to make

“When it comes to where to even begin, it starts with

Ikenna Nwaiwu, API Product Owner

stoplight.com The API Roadmap — 8

A Foundational Understanding of Key Resources: Learning the

Learn from Leaders in the Community (like in this eBook!):

Get the Right Toolset: When you’re ready to actually start

“Whether you’re just getting into development, whether you

Brenton House, VP of Digital Evangelism at Software AG

stoplight.com The API Roadmap — 9

stoplight.com The API Roadmap — 10

James Higginbotham, Executive API Consultant at LaunchAny, shares his tips

Here are his four main ways of treating APIs as products:

Adopt an Outside-In Perspective: Adopting an outside-in approach

Put yourself in the shoes of your client and understand their

You need to start by aligning with what’s needed in the market-

If you build an API program without considering the needs of

Form a Team with a Product Mindset: Assemble a dedicated team

A team that treats your integration assets as products can

By centralizing knowledge on how APIs are designed, a more

stoplight.com The API Roadmap — 11

Adopt New Tech Incrementally: Just like any other business