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 is to test your API, not peripheral tooling. If you have a long list of dependencies that need to be set up, find a way to do that configuration beforehand. Consider things like:
- Creating distribution code with basic configuration steps already done.
- If a database lookup will be required, pre-populate the database with useful values. For example, if you’re testing an API for search as a service, have some JSON documents already loaded up
- Create a reusable development environment. This could be:
- a Virtual machine, if you need complete configurability
- Codesandbox, if you are willing to pay for a hosted environment
- A Docker container
- Create API keys and tokens ahead of time. If you don’t have an easy way for customers to sign up for a free trial, pre-provision the required credentials so your tester doesn’t have to worry about setting up an account
Include conceptual documentation
Most of your customers will come to you with the goal of solving a specific problem. Remember that at Usabl, many of our testers are full-time engineers or students who may have no familiarity with your product. Make sure you share enough conceptual documentation with them that they understand why your product or service is useful.
Write implementation-agnostic tasks
When writing the actual tasks, use generic language without relying on your specific API. For example, if you were going to test Stripe’s payments API, rather than saying “use the Charge object to initialize a PaymentIntent,” you should say “charge this customer $5 for the service you just provided them.”
Also, remember that many acronyms have different meanings in different contexts, and not all developers have the same backgrounds as you do. Fully define all acronyms to minimize confusion.
Usabl blog
Learn more about how API usability impacts your business
