A public API that is used by thousands of developers needs to be so simple to understand that it’s nearly impossible to make a mistake with.

When you have to integrate an API, it can feel complex and frustrating if you have to guess your way through it because there is a lack of documentation and working examples or if the error handling is unhelpful. It is why, in a recent SmartBear survey of 1,898 developers, 38% identified “ease of use” as the most important factor behind choosing an API.

Even more importantly, incorrect assumptions about API integrations can lead to significant negative effects in the real world. In the case of Impala, it might mean a traveller being quoted an incorrect hotel rate or being charged for a breakfast they thought was included.

Needless to say, we’re working hard to avoid these scenarios and one of the main ways we do so is through UX research.

Don’t assume that developers build great APIs

Building open APIs is not the same as building UI-based products.

When releasing an API, you must be aware that developers will build businesses on it and that they expect it not to break their production applications. You can’t experiment with an audience that depends on the stability of their business’s building blocks.

Unfortunately however, API design is often not tackled with the same rigour as other digital products. While few modern product development teams would forego usability testing and research for their UI designs, it is more common for teams to do so when designing an API.

They will assume that, because they are consumers of APIs themselves, they must be able to design easy-to-use APIs for their customers’ developers. This is certainly not true and the sheer number of hard-to-understand and inconsistently designed public APIs out there show how dangerous this assumption has proved to be.

The reality is that no-one is very good at understanding how others might use their API and everyone finds it hard to predict where others may struggle. This is why public APIs require the same, if not more, research and validation than UI design before they’re built and released.

While there’s plenty of content out there about prototyping and usability-testing UIs, there’s very little about how to do the same with APIs or how this can be achieved without too much effort. So, here’s a peak at what we’ve found works well at Impala.

How to design and test an API before building it

Before I go into more detail about what’s involved at various stages, here’s the tl;dr of what we’ve found works best:

1. Talk to customers to find out what they need in terms of the functionality required to get the job done.
2. Document what the API should look like. We use the structured OpenAPI format to describe our APIs.
3. Get your team’s input on improving the API by sharing the docs with them.
4. Schedule UX research sessions with developers. You should organise up to six 50-minute sessions (all remote, live & moderated) to take place on one day.
5. Create a mock API for UX research sessions in Mockoon. Use OpenAPI as the basis, then make it more life-like using Liquid templating and rules in Mockoon.
6. Run sessions on Lookback or Zoom. Make sure a few people from the team join each session to observe and take notes.
7. Use initial feedback to adapt the mocked API immediately. If the first two participants struggle, change the mocked API and test an iterated version with the others.
8. Write up conclusions and action items at the end of the day. These should be shared with your whole company.

This is a simple step-by-step process that any engineering team can follow. As some steps may be less familiar than others, here’s some more detail on the tools and processes you can use at various stages.

Finding developers for user research

To ensure your UX research is as successful as possible, you need to prepare a clear structure for your sessions and recruit a wide range of developers, so you can produce a lot of insights as efficiently as possible.

Schedule fewer sessions, with greater depth and moderation

For most API design, five sessions of set tasks and questions are usually enough for the important patterns and misunderstandings to emerge. Anything more yields diminishing returns.

Also, it’s great to be able to dig in and follow up on what a developer says or does, so it’s a good idea to use moderated sessions rather than unmoderated ones. We try to schedule a session for an hour but structure the tasks to take 45 minutes, so there’s always spare time available.

Recruit on your site, on public Slack channels and on freelancing platforms

Depending on what you’re testing, it can be helpful to find developers who have used your API before or are interested in using it. Tools like Ethnio allow you to intercept visitors on your site and offer them an incentive to participate in research.

It can also be helpful to explicitly recruit people from elsewhere, who have little to no context about your product. This is important because many developers are hired to integrate your API without much domain knowledge. In our case, this may include those who don’t understand common travel industry terminology.

We have found hiring developers on freelancing platforms like Upwork to be a pragmatic and easy way of scheduling these sessions.

For the best results on Upwork, make sure to set a fixed-price incentive, put the date and time of the sessions in the title and specify that no prep is needed. Upwork also allows you to add screener questions, which we use to double-check the following details:

• When was the last time you used an open RESTful API and who provided it?
• Are you available at the time indicated in the title (Central European Timezone, CET)?
• Are you comfortable with us recording this video conferencing and screen-share session to support our product development? (We’ll use it to record notes after the session and might share portions with our team internally.)

Find developers with different programming language preferences

Make sure to recruit a diverse set of people so that your API design is understandable and works for every developer that could use it.

To do this, look at your API’s target audience and recruit a good mix of people, including:

• Folks who prefer programming languages that are strongly or weakly typed.
• Participants who consider themselves backend, frontend or full stack developers.
• Inexperienced starters as well as seasoned professionals.
• Those who are well-versed with RESTful JSON APIs or might frequently use SDKs, GraphQL, SOAP and other (more modern or old-fashioned) flavours of APIs.

Faking it until you make it — literally

With a range of developers ready to help you test and improve your initial design, you can use Stoplight Studio and Mockoon to mock up an API for them to interact with during the research sessions.

Design and describe with Stoplight Studio

Every new feature starts in Stoplight Studio, a web-based editor for OpenAPI (previously Swagger) documentation. We start by describing new endpoints and fields, complete with examples.

We edit in Stoplight, and host and version-control our OpenAPI documents on GitHub, which means making changes and committing them into a separate branch and pull request for review by others on the team is easy.

Create interactive mock APIs with Mockoon

Mockoon is the answer to just about every mocking need you might have.

It’s a desktop application that allows you to import OpenAPI (Swagger) documents and create mocked APIs hosted locally. It makes it incredibly easy to adapt them to be life-like, even with very basic or no coding skills.

The most useful features in Mockoon are:

• Shopify’s Liquid templating language, which makes it easy to repeat items in a list or include parts of the response conditionally. For us, this might mean returning 50 fake hotels in a list or only returning hotel rates if the participant has specified dates as input in the request.
• Faker.js, which allows you to generate fake names, random numbers, lorem ipsum text or names. In the example above, this means the 50 fake hotels have different ids, names and descriptions, making the response look more realistic.
• Rule-based responses, which allow you to mock error cases based on simple rules. As an example, you could mock returning an error if a mandatory query parameter is missing or returning the full result if it exists.
• Runs locally and changes are instantaneous. This means you can modify API responses during the session while your participant is using the mocked API.

Let participants access your mocked API remotely with ngrok

While it’s helpful to be able to run your mocked API locally and edit it in real time, your participants will need to access them online via the public internet. ngrok bridges this gap and tunnels what’s only available to you from Mockoon to a public web address for your participant to use.

Running your research with Lookback

Lookback is like Zoom but made for user research. It allows you to create links for your UX research sessions and share them with your participants.

You can configure instructions to show participants before they join a session, while the session is ongoing or after the session has ended. It also allows you to automatically open a url in your participant’s browser when the session starts. This could be Postman for Web (so your participant doesn’t need a REST client to participate) or the Stoplight-generated documentation pages for your feature.

When a participant joins, Lookback guides them through sharing their camera, microphone and screen. When they’re ready to start, you’ll see a message in Lookback. Once the session has started, an unlimited number of people on your team can silently pop in and out of the virtual observation room without distracting the participant.

Lookback automatically records the session and allows the observers (or the facilitator) to take time stamped notes that make it easy to find soundbites of interesting insights later.

Integrating what you’ve learnt into your API design

At the end of the research day, make sure to go through the time stamped notes of the sessions, write down any conclusions and integrate these learnings into your API documentation. Then off you go! You're ready to build an API that is validated and easy to understand.

What’s your experience of testing whether your API-based products work for developers? Are you doing anything differently that we could learn from? Let’s chat!

Want to build great APIs? Check out our open roles!