Is anyone doing UX for APIs?

APIs may be an agreed way for applications to communicate, but we should be building them for humans.


  • Humans test the API.
  • Humans write the applications that will use the API.
  • Humans use the applications that use the API.

With this in mind, I have some questions:

Who is doing UX design and Testing for APIs? If yes, any tips or suggestions?

Maybe instead of User Experience you can call this, Developer Experience.

Who is reviewing API documentation , and raising bugs where Doc’s are insufficient?


Haha! Love the perspective :blush:

Would love to know what perspective others have.

In my experience, it was either,

  1. Just pure CRUD
  2. Or follows the access pattern of what the app client requires.

how do we define UX for API?

We have a user documentation review activity for every release where the OpenAPI YAML gets validated for the content. We check

  • Does it have enough data,
  • is the data correct,
  • does it have enough examples

We also share a postman collection for the Devs which makes it easier for them to get started.

For the actual API responses especially the error cases - we can check whether the messages are clear and specific.
“The request could not be processed due to an error in this param” is better than “An error occurred”.

1 Like

Thank you very much for sharing your approach. I haven’t defined UX for APIs yet. I’m very curious to find out what others are doing so I can up my game!

Me too, thanks for sharing!

I think it’s difficult to think of UX in isolation of the integrated system. Maybe I am better off thinking about the “Developer Experience”.

But then, I think API and service design can impact how users interact with the downstream products.

For example, a lack of good paging of filtering might cause poor UX, because you end up with the client pulling way more then it needs and processing locally.

1 Like

We design API’s before the are created and we adjust accordingly.
We groom them also, some examples at what we look at:

  • if we need a patch when a put isn’t sufficient
  • http codes (we have standards for it) including error handling
  • the resources of an API are very important, it should always be plural nouns so for example /user/jeff should be /users/jeff
  • we validate the design and order of the values in the json, date values are consistent
  • API’s should be easy to read and every value should be clear to what it does/stands for
  • we check if we need to limit the GET requests, let’s say you are retrieving all customers but you only want to see the first 100. Do we need it/Do we need to implement it?
  • Don’t overfetch data, if you don’t need to!
  • Upgrading the version of the API

That’s awesome.

What type of sessions do you conduct to carry out these reviews and changes ?

1 Like

That’s very true.

I have been talking to my project teams about the same issue.

The argument that backend teams don’t need to be a part of front end discussions is just straight up bad.

They are very much important in providing a better UX experience to the end user. And API designs are a huge part of it.

Just to add another example, filtering is a good one I always use.

1 Like

If it’s in the design phase, we just do it like a grooming, like it should be this and that.
After the design of the api has been made, it’s like a “code review” basically. (most of the times it’s like this)


I wonder if it would be a good idea to do user research on APIs just like you do for designs.

Interview front end developers individually and then test the initial API specs on them to see if they can achieve what is required ?

1 Like

Ohhh I like this idea! I might try that.

If you try this let me know how it goes.

1 Like

Where I’m at right now the BAs and/or developers work on the API documentation. Since I’m the only tester in the team they always ask me to review the docs and share my input. A well document API is easier to test and having understandable API documentation helps whomever is consuming the API.

1 Like

Nice, that sounds like a very reasonable setup!

Do you, or your BA’s ever get feedback from customers on the documentation / API integration exprience? (before or after developing the API)?

1 Like

Do you, or your BA’s ever get feedback from customers on the documentation / API integration experience? (before or after developing the API)?

Yes, we do, the project is about developing APIs which insurance brokers can consume to get data required to re-sell insurance to their customers so based on what they need (and the feedback we keep getting from these brokers) we make new endpoints or adjust existing ones to accommodate their needs. Before an API goes officially to prod they usually have some remarks or change requests which they send to one of the BA, who kind of acts like a proxy in this situation.

1 Like

One of the more interesting things I’ve done as a tester is to take an API and create Swagger documentation for it as part of the testing - complete with examples.

That was a fun learning experience. There are still aspects of using Swagger with a dot net project that I’m not sure of (like adding links to static web pages and how to set up authentication so that users only see the parts of the API they’re allowed to access), but it was definitely rewarding.


Oh what fun! I’ve not actually done this myself yet, but I think I probably should give it a go!

1 Like

We’ve done it with Postman also, and you can publish the API’s as Docs easily and everyone of your team can check them out also. On the website of postman itself, you can view the docs also and change the environment also (QA/DEV/ACC/Prod) and all the data will change with it, also (live in the docs).

Pretty sweet :stuck_out_tongue:

1 Like

From a testing perspective, I’ve loved working on projects that use JSON:API spec in their design: Looks like it confers some additional benefits but I primarily liked it for its readability.
I second the people mentioning error handling/messaging. That goes such a huge way towards making integration testing doable and efficient.