I recently wrote about the Right Way to API (which is via the design-first approach, for those who haven’t yet read it). In today’s article, I’m going to build on that guidance with some specifics about what NOT to do.
We always tout the “design-first” approach above all else when it comes to your API strategy — but what happens if you don’t follow that advice?
Here are the top 3 “wrong ways” to API:
1. Operating with a Code-First Strategy
The best way to start off on the wrong foot is to not plan anything and just start banging out code with only a notional idea of where you’re going and how you’ll get there.
If a company is serious about building a scalable, world-class technology program, taking a code-first approach may be the worst thing they can do — yet it’s an easy trap for even experienced software developers to fall into.
A typical code-first scenario often unfolds over time as developers create new endpoints and APIs to release updates and/or new product features. Basically, the APIs are created as byproducts of the development process rather than as unique products to be consumed by a broader audience.
That is code-first in a nutshell: Completely oriented to developers and unconcerned about other potential API users.
The problem with a code-first approach is that even well-designed APIs developed this way are predestined to fail. Here’s why:
The success of an API is based on its adoption and use by more and more users. As adoption trends up, most of the new users will not be developers — they will be people trying to solve problems as quickly and easily as possible. If an API is not intuitive and applicable to their context, people simply won’t use it.
Design-first, on the other hand, keeps end users in mind from the outset. This approach is based on a thoughtful, intentional design process that provides a better experience for both developers and end users.
You wouldn’t try to build a house without a set of blueprints, right? You would first think about who’ll be using it, how much space they’ll want, and what features they’ll need. Design-first takes the same thoughtful approach to building APIs.
2. Forgetting to Treat Your APIs Like Products
If you really want to bomb your API program, pretend that APIs aren’t products. Try it. I dare you. You’ll have a hot mess on your hands. Because APIs are absolutely 100% products — even internal APIs.
While external APIs are the celebrities of the API world, the vast majority of APIs are internal. RapidAPI’s 2020-2021 Developer Survey found that 75% of developers reported working on internal APIs.
Internal APIs are developed to solve business problems and/or make selected datasets more visible to internal users. As such, it’s easy (and wrong) to think of internal APIs as discrete tools with limited use cases. But the reality is far more exciting.
There are numerous examples of internal APIs evolving into wildly popular external APIs. Often enough, someone realizes that a certain dataset exposed by an internal API would hold massive value for external audiences.
And when you think of APIs this way, it’s less tempting to wing it with an improvised code-first approach. The business potential warrants time, investment, and a thoughtful, design-first approach.
APIs are not just software or a means to an end. They have the potential to ignite growth and innovation while building deeper, data-driven relationships with customers and partners.
I think of APIs as technology ambassadors — the digital face of a brand. And as such, they should be designed and crafted with care, just like any other product or service your company offers.
3. Isolating Your APIs/Not Including Users in the Process Early On
If you want end users to really hate the final product, lock up your APIs for the entire design and development process. Do not engage the target users — and definitely do not seek their input or feedback about the features, functionality, and user experience.
If you can pull that off without slipping up, your APIs will be completely miserable to deal with and users won’t touch them.
On the other hand, if you would like people to use and even enjoy your APIs, you’ve got to bring end-users into the development process early.
It makes sense that if your APIs are your brand’s ambassadors, you need them to be well-socialized. And there are several ways to collaborate with users and partners, to make sure you don’t end up with a weird and awkward hermit of an API.
First and foremost, start with a design-first API program that brings end-users into the design process early on. Developers need to solicit their feedback about what the API needs to do and how it should feel to use it. Successful API programs engage users early and keep them involved in the API design process to make sure development tracks with users’ expectations.
This step is equally important for internal and external APIs, as the users involved in the process are likely to become the early adopters who will initially drive acceptance and use of the product.
Next, think hard about the partners you bring into the API. Yes, you will likely need partners. An API is only as good as the technology it connects to, so it’s critical that the partner technologies both function well and drive traffic for the API you’re developing.
Google Maps is a great example of a fantastic API partner. How many thousands of APIs rely on Google Maps to complement their shopping, navigation, or exercise apps, for example?
Making sure the API will work well with the designated partner should be a high priority for the development team.
You should also use a mocking tool such as Prism to mimic your API’s behavior as you build it. Prism is an essential tool for collaboration, as it enables developers, partners, and end-users to test and experience the API as it comes together.
This level of engagement uncovers major disconnects or red flags much earlier in the process when problems are less labor-intensive to fix. Prism basically gives your ambassador a dress rehearsal well in advance of the big event.
Take the Easy Way Out — Design-First
It’s a lot easier to build APIs the right way, using a design-first approach. It does take more planning and a sustained commitment, but the building part is virtually painless compared to a code-first approach — and you get a far better outcome.
In fact, using the wrong way to API will typically cost you a great deal more time, money, and misery. There’s just no good reason to put your developers and customers through a terrible development experience that has no benefit for anyone involved.
If you’re ready to launch an API program, I encourage you to check out Stoplight’s API Design Blog and subscribe to our API Intersection podcast. Most importantly, start with a design-first approach so you can maximize your ROI sooner and avoid the predictable pitfalls that come from just winging it.
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 they can spark growth and deeper relationships with customers and partners. Feel free to leave a question below and join the conversation.
