One of the hardest things about finding out your API is unusable is deciding what to do with that feedback. Do you release a new version of the API that’s more usable and support both versions indefinitely? Do you deprecate the old version and risk losing customers who are now forced to migrate?
Wouldn’t it be better if you could just avoid the problem entirely? This is where the design-first API process comes in. Rather than building an entire API from scratch, teams using the design-first API process build a prototype of an API, before building the backend functionality. In this way, the design-first API process lets you quickly iterate on usability improvements while it’s still early enough to act on what you learn. In this blog, I’ll walk you through how you can implement the design-first process at your company.
As the API ecosystem has grown more mature, we’ve started to see a number of tools for doing API mocking. Just like how designers of graphical user interfaces start in a tool like Figma before writing a single line of code, designers of APIs can use API mockup tools before writing any backend logic. Some good options include:
It can be tempting to try to build your whole API surface at one go, but remember that your goal at this stage is to maximize opportunities for learning. That means starting with a critical user journey. If you are designing the APIs for a machine learning platform, for example, a critical user journey might be:
Using the mockup tool you selected, write the APIs you think you would use for this one critical user journey.
While we would all like to believe our APIs are self-documenting, consider taking the time to write a basic conceptual overview of your service. This will be useful not just for helping testers build context but also will save you time once you are ready to release your API. You should cover things like:
Now for the most important part: find some customers and show them what you’re building! For the most valuable feedback, you want to test with developers who have never seen your APIs before. These could be people in your own company who work on different teams, or potentially new team members who are still learning about your technology stack.
You could also consider using a professional API usability testing service like Usabl. The advantage of using a professional service includes:
Once you have seen what your customers have to say about your design, iterate! Consider:
By incorporating design-first practices into your API development, you can ensure you get your API surface right the first time, minimizing support costs for your team and increasing customer satisfaction.
Learn more about how API usability impacts your business
Make your quickstart harder
When I was at Microsoft, one of the Azure Machine Learning team’s strategic initiatives was “five minutes to wow.” Our aim was to ensure that a developer new to Azure ML should, within 5 minutes, achieve such a surprising/useful/novel outcome with Azure ML that they say “wow!” Inspired by the goal, I worked on a […]
How Courier is using Usabl to unlock developer virality for its multi-channel notification API
“Videos from Usabl are timely, informative, and actionable. They help us uncover previously unknown issues in our developer experience and build internal consensus around real solutions” – Donnie Wang, Growth PM @ Courier Courier’s API makes it easy to send multi-channel product notifications reliably and in a way that is respectful to the end user. […]
We evaluated the usability of 4 leading eSignature APIs
Most were surprisingly bad eSignature as a space has been heating up for a while now. Look at Dropbox’s $230 million acquisition of HelloSign in 2019 or PandaDoc’s recent unicorn status for evidence of the growth in interest in the sector. The high valuations reflect the fact that signatures are involved in some of the […]
Why you, a UI-first business, should care about developer experience
What do the video game Doom, shopping malls, and Salesforce have in common? (No, it’s not that they all are fun ways to spend an afternoon). Doom was remarkable as one of the first PC games to support “modding.” Shopping malls are only as successful as the tenants that rent space within them. And Salesforce […]
Tag yourself: a framework for developer experience maturity
As we’ve built out Usabl’s platform for getting feedback from real developers, we’ve spoken to dozens of companies building API- and developer-first products for everything from payments processing to security scanning. In each conversation, we’ve consistently seen patterns in the way these businesses engage with developers. In this piece I propose that developer-first businesses can […]
Understanding the developer activation funnel
Your developer experience should be your best marketing tool As we’ve interviewed companies building developer-facing SaaS products, I’ve seen some common patterns emerging in the way companies build for developers. In this blog post, I’ll explain at a high level the journey that a developer will typically take with a SaaS product. To the best […]
API usability for developer-first products
It’s 2021, and developer experience is coming more and more into focus. In fact, companies are hiring product managers specifically with the goal of improving their developer experience. Staying close to your customer matters in every industry. Though it feels harder to get feedback as developers are expensive and specialized, Usabl is focusing on helping […]
Writing your first task
Writing your a task for an API usability test Let’s say you’ve gone through the steps here and chosen a well-sized task that tests your riskiest hypothesis about the usability of your API. You’re now ready to actually write your first task. How should you go about doing this? Minimize configuration time Remember, your goal […]
What part of your API should you test for usability?
So you’ve decided you want to run an usability test to discover ways in which you could improve the developer experience with your APIs. Congratulations! The next step is to decide what exactly to test. You might be thinking of simply taking one of your public samples, removing some of the code, and asking the […]