User experience design for APIs

Glad you like it. It's in good hands indeed.

Great, except for this…

> (in general, always use ValueError and avoid assert).

ValueError is for when,

> an argument that has the right type but an inappropriate value, and the situation is not described by a more precise exception

(the docs explicitly note only for builtins, but I'm frankly okay w/ people using it in their code.)

You should not be raising this when you should be raising AssertionError, however, the two conditions are very different; the latter is for conditions that should be true but for some reason aren't. I find these usually crop up when running through a bunch of ifs:

  if a:
  elif b:
  elif c:
  else:
    # *One* of the above should always match, in this case.
    # This branch should never be taken, and it wasn't any fault of the user we're here.
    raise AssertionError('good description of the situation')

Attempts to restructure the above are usually fairly bad: you can omit the `else`, but then execution will never take any branch, and if the branches do something like initialize a variable that the code following the branches will make use of, you're doomed anyways, and it's better to bail in an informative manner. You can meld the last elif and else together (i.e., the else just handles case C above), but then it also inadvertently handles unexpected states D, E, etc. too.

IMO, AssertionErrors should indicate bugs in the called API. ValueErrors indicate bugs in the caller's use of the API.

(You may choose a less "destructive" method of asserting, such as logging, but in my experience, these get lost, and if you're in an undefined state then you still need to find some way to repair that state, and in my experience most attempts to do so are more trouble than they're worth. It's better to fail earlier and harder and louder, s.t. bugs are discovered and swiftly fixed.)

Not an "API", but git has a terrible UI... yet the error messages (and guidance included in response to correct commands) are the best I've ever seen. They guide the user through a typical workflow.

A similar guidance is pop-ups in games (e.g. when next to car, "F to enter").

I thought it was a good idea when an error message says

    bad request type, see http://company.com/API/ce32h 

except that it always seems the company forgets and removes the page.

maybe that could be fixed to some degree in a build step

Wow, the example in the article is an extremely verbose error message! But still, detailed and helpful error messages really do make the developer's life easier.

When building API end points, I take a different approach by including both messages and message codes, as well as a general "result" code (to make it easy to determine if it's a basic success/error result (also including the right HTTP code)).

An example that I'm working on right at the moment:

    {
        "result": {
            "code": "error",
            "message_code": "too_many_user_agents",
            "message": "You have sent %s user agents; this is more than the maximum allowed per batch (%s user agents). Please send fewer in each batch."
        }
    }

The message describes the problem; what they did wrong, what the limit is and how they can fix it so it doesn't happen again.

As well as this, the developer can easily check that the response code was an error, and there's the message_code - this will NEVER EVER change for this problem, so a developer could write code to specifically deal with that scenario.

However there's also a human readable message, which may potentially change (perhaps a grammar or punctuation fix, or if it included a URL it might change one day...)

I've found this approach is the best sort of middle ground.