Nobody Has Time to Learn Your API

“If they’d just learn how to use it correctly…”

If people are shooting themselves in the foot with your API, it’s probably your fault. If your defaults are unsafe for production use, your API is broken.

Most of the time, your API is going to give someone access to some small piece of data or functionality, and learning how to use it is a tiny footnote among the hundreds of things that need to be done in order to deliver some product. People are going to swoop into your documentation (you have that, right?), pick the first thing that sort of looks like it will work, try it, and then move on. Rather than lament that the unworthy masses aren’t doing their homework, you need to design with their limited time in mind: