How To Build APIs That Delight Customers
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.
Choose a mockup tool
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:
- Mockoon – free to use and open source, comes with a GUI
- Stoplight – free trial version with enterprise plans, also offers a centralized portal for maintaining API documentation and artifacts
- Postman – API unicorn with free trial options, desktop and browser-based tooling
Define your critical user journey
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:
- Creating a cloud compute cluster
- Submitting a Docker image to that cloud compute cluster
- Downloading the artifact of the run
Using the mockup tool you selected, write the APIs you think you would use for this one critical user journey.
Don’t forget your documentation
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:
- What problem are you solving?
- What pre-requisites are there to use your API? Do customers need an API key or an account?
- What are the various nouns and verbs a customer will interact with in order to accomplish the critical user journey you defined above?
Show to customers, and iterate
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:
- Faster turnaround time – most tests complete within hours
- Consistent quality – all testers are vetted and trained to provide actionable feedback
- Self-service scheduling – don’t worry about finding testers or setting up time with them – we’ll handle all the details
Once you have seen what your customers have to say about your design, iterate! Consider:
- Did the names of each of your API routes make sense?
- Did customers understand which sequence of actions they needed to take to successfully complete a task?
- Did customers understand why the API was useful?
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.
Usabl blog
Learn more about how API usability impacts your business
