The API lifecycle has two parts—the awesome and the suck. The suck is the activation energy of acclimating to a new API, learning its primitives and quirks. Later on, it’s downtime or an unexpected 500 response. The awesome is easy—it’s the API working for you, giving you the value (or data) you want out of it.

As an API builder your job is to minimize the suck and maximize the awesome. Start early and start structural. Design your API to be as friendly—as human—as possible. You want your API to be dead simple, so easy to integrate that an idiot could do it.

Here are some qualities of a human-friendly API, all born out of my experience as a stubborn, obstinate developer building APIs.

  • Include human-friendly context and references (links to docs) in every error message. And if a request is missing required fields, don’t be an asshole. Tell them what’s missing

  • A GET request to your API host should return an error or redirect that is friendly to non-technical folks (who copy-and-paste your API host into their browser…)

  • Add context to API tokens and IDs—like btok for a bank token versus ptok for a payment token. This humanizes them and allows for better errors when developers give you the wrong type of token (they will) without security compromises

  • Make secrets easily rotable by the developer and have distinct secrets for each API environment. Developers will check it in to a repo, share it in Slack, send it in an email, etc.

  • If you get the same question multiple times, something about your API is confusing. You are the problem

  • Every API response should include a unique request ID that you can look up in your logs

  • Keep libraries and sample code up-to-date. Developers don’t use the API directly, they use client libraries and ship copy-and-pasted code snippets to production

  • Meet your developers at their level, not yours. Provide tools that support their preferred languages and style, regardless of whether you personally like it

  • Build and maintain a real product against your API. You will better understand your developers’ pain points and frustrations