The Right Way to API

  • Steve Rodda
    Steve Rodda
    December 1 2021

Learn more about the right way to by using Stoplight.

Get Started

It's no secret that APIs are one of the fastest-growing and most impactful technologies affecting digital commerce, and the trend just keeps accelerating. Why? Well, thanks to Marc Andreessen, we already knew "software is eating the world." What I'd add is that APIs are the teeth. Let me explain…

APIs amount to how systems (like software) talk to each other without pesky human "users" getting in the way. APIs are an abstraction layer to a process or set of processes that are made available to queries from outside their own system. In simple terms, APIs make it easy to add complex processes or sets of data to a piece of software without having to code it from scratch.

The ability to componentize software in APIs makes it easier to add on to and/or connect with other things. In business terms, it's a software development model that allows business leaders to solve problems and exploit new opportunities more quickly and simply than ever before.

"Unbundling" software into APIs has been around for a while. In fact, it was reported in the Harvard Business Review this past year that Jeff Bezos, founder, and then-CEO of Amazon, mandated API-first development as early as 2002. I think I can go out on a limb and say that model has likely been a significant contributor to Amazon's ability to innovate faster than anyone else in the market — and, frankly, the world.

Beyond the likes of Amazon, which may transform its business through a comprehensive shift in the architecture of its existing technology, we have also seen a global rise of companies founded exclusively on an API-based innovation. Think Stripe, Twilio, and Sendgrid (in full disclosure, and not surprisingly, we here at Stoplight work with each of these companies as both a customer and, in some cases, vendor).

We see this spectrum in full display with our customers, ranging from 21st-century tweenagers to global conglomerates founded in the late 1800s (like Calendly and Schneider Electric, respectively).

Business leaders (perhaps such as yourself) have caught on to this trend and, more and more, they're seeking out the technology needed to manage APIs. According to a report by Markets and Markets, the global API management market size is forecasted to grow from $1.2 billion in 2018 to $5.1 billion by 2023. APIs are reshaping the marketplace and companies' relationships with their employees and customers.

Whether or not you're in the "tech" business, APIs are likely to become a much more significant factor for your company, competitors, and customers. So I feel it's fair for me to say it's wise to start thinking about how to incorporate them into your business before it's too late.

Getting Started

I'm just going to come right out and say it: There is a right way and a wrong way to create APIs. If you're new to APIs, it can sometimes be difficult to decipher which is which. For most businesses, an ideal approach would result in creating the highest quality API products with the most efficient, cost-effective, and headache-free process.

At Stoplight, we have a very strong (and biased) opinion that, based on those criteria (efficient, cost-effective, and headache-free), design-first API development is the right way.

A design-first API program is based on the idea that APIs are products that should be planned and created in an organized, thoughtful, and intentional way. I've blogged about why design-first is the best approach for APIs if you'd like to learn more about that.

Essentially, a design-first mindset lets you lead with an intentional design that makes for a better developer and end-user experience (i.e., happy employees and happy customers for you).

It's just like building a house. You wouldn't try to build a house without a set of plans, right? And if someone did just wing it, without doing any planning upfront, what do you think that process and outcome would look like? More than likely, it would be a nightmare for everyone involved.

That's why every serious building project starts with the design phase, where someone assembles a team that sets the vision and agrees to the process, goals, and finished product. Stoplight advocates for the same approach when building APIs.

Why Design-First Matters

APIs are catalysts for growth, innovation, and building deeper relationships with customers. Think of them as the behind-the-scenes, technology-driven ambassadors of your brand. A poorly-developed API is a bad look for you — and a terribly disjointed and clunky experience for your developers and end-users. These outcomes result from uncoordinated, build-the-airplane-as-you-fly-it approaches, and they are certainly not what any business is hoping for when it invests in digital transformation. Thankfully, all of that drama is completely avoidable.

Design-first API programs save time and money because they have more predictable processes, less duplication of effort, better coordination, and more ROI from reusable components. Check out Calendly's story if you would like to see how a design-first API program leads to smoother implementation, improved consistency and governance, and documentation that's always up to date.

Why is “design-first” even a thing? Well, think of it this way: The original approach to API-building essentially involved developers building APIs solely for specific developers. Some may call this approach "code-first." But the reality is that as more and more people engage with APIs, more and more of them are NOT developers.

If we follow along with the human shelter (aka house) metaphor, the code-first approach would be like an experienced backpacker pitching a tent in the wilderness. Sure, another experienced backpacker who comes along and needs a place to sleep, might be perfectly fine figuring out how to get comfortable or at least stay dry, but most of us would likely end up huddled under a tree.

These days, APIs are made for a much larger community of developers with different needs. APIs need to be built more like a house, than a tent - so that it provides shelter for more people and needs to be intuitively usable, and, importantly, that it fits into a context with other services and support for the people who will inhabit it. A design-first approach is about focusing on the needs of many different developers and systems with different purposes and implications on the original structure.

It's clear that we're moving toward a globalized and interconnected operating environment for technology with APIs at the crux of it all. Accordingly, we need to think about building APIs, not just for the original developers and internal teams, but also the end-users and community that will potentially interact with them. In our vision for design-first, the very foundation of each API is rooted in designing for a broader global audience.

Unified in Empathy

Design-led processes are driven by empathy. For most of us in business, that means being focused on cultivating empathy for our customers, to better understand their needs and deliver the right experiences for them. By establishing design as the first step in the API development lifecycle, we help cultivate that empathy.

We've all seen examples of systems that were designed without a focus on the end-user experience. Famously, when early tech companies (okay, super big and important ones) first set out to build an operating system for computers, the resulting experience tended to work well for developers. But many of us (i.e. everyone lacking a computer science degree) were left staring blankly at the screen or calling support for help getting started.

On the other hand, when more companies (yeah, other big ones) decided to include dedicated designers in the product development lifecycle, they produced a device that even a toddler can operate. With high performance and near-universal adoption, the iPad is a great example of what's possible when design-first thinking is implemented from the get-go.

Now, imagine that ease-of-use happening with your APIs and how it would contribute to your end-user experience. I'm not one to consider that joyful, per se, but it gets pretty darn close when we're looking at the developer experience, too.

My point is: Development works better when it comes from a design-driven approach.

The Future Is APIs

APIs aren't done disrupting markets. I think they've only just begun — and they certainly aren't going away. They are a megatrend that business leaders need to understand and build a scalable strategy around if they want their companies to be successful long term.

How do we do that? Through design-first, which is the best way to ensure your APIs are treated as products, your end-user is kept in mind, and the developer experience is at the forefront of your process. You consider the entire ecosystem of the API, ensuring that the whole global metropolis will have a positive experience with it.

Are you considering the investment it will take to launch your company's API program (not to mention the amount already invested in the people who will be implementing it)? Get started on the right foot so your company can realize positive impacts sooner.

It's time to build for tomorrow's market realities, and APIs will be a big part of the equation. How are you planning to get started?

If you're looking for some ideas, feel free to subscribe to our API Intersection podcast or take a look at this recent blog from Stoplight CTO Jason Harmon about how to start a solid API program.

I'm the CEO of Stoplight, a software company focused on API design and development with a design-first approach. In the coming months, I'll be blogging about APIs and how we help our customers realize outstanding business outcomes. Feel free to leave a question below and join the conversation.



Peek-a-Boo (1)

Subscribe for the latest in API Design

By submitting this you will be receiving our latest updates on post.

Take a Listen to API Intersection

The podcast on the intersection between API design & digital transformation

Related Posts