How to tell if an API is bad

a screenshot of the Tableau REST API documentation

Hey look, they highlighted the part I hate:

Note: After creating the user, you must set a full name, password, and email address for the user with the call to Update User.

I have a feature suggestion, perhaps this is daft, but if I must update a user with information via a different call after creating it, I don’t know, maybe I could just provide that information when creating the user?

To be fair, a nice attempt has been made to build the API around resources, which means it’s a REST API! And that is good. But what would have been nicer would have been considering some use-cases. Why are people going to use the API.

My use case: When a new user comes in, create a Tableau user in a specific group. If the user already exists in Tableau then update with the latest data.

This requires the following API calls:

  1. Sign-in, because the API is secured with a token but you need to get this from a username-password combo…
  2. Check the user exists on the site
  3. Create the user against the site if they don’t exist
  4. Update the user
  5. Create the user against the group (we can let this fail if they are already in the group because we don’t need anything from the result of this call)

Maybe GraphQL will save us all?