API Design is UI for Developers

I've been thinking a lot about APIs and their design recently.

I stumbled on this fantastic quote from Greg Parker:

When I first started learning C++ (back in the bad old days) I was convinced that any 1st year student could design a better programming language. One which behaved in a sane fashion without a lot of legacy cruft. In many ways, PHP is that programming language. It's simple, logical, and works without having to know lots of esoteric computer science.

I see API design in the same way. Most of the APIs I come in contact with were obviously designed by the original developer for the original developer - with no thought of those who would come after her. Often, they're designed for one specific internal usage, reluctantly opened to the public, and never updated to account for how people actually use them. Oh, and you can forget about decent documentation!

One hackathon I went to a few weeks ago had a Developer Relations employee stand up and say:

Who wants to use our API? It uses SOAP - sorry. If you want documentation - come see me because it's not on the website. Oh, and it's read only. Let me know as soon as possible because it takes 6 hours to approve your API key.

This is madness. Developers are human too! They need some HCI love between them and their APIs.

So, here are my hastily scribbled thoughts on what an API needs at a minimum to entice the busy developer.

I don't think any of these are Earth-shattering, but it's amazing how many APIs fail to meet even these basic requirements.

Easy Access

  • Don't make me register, set up an account, or fill in a load of forms - I just want to see what I can do with you before I make a commitment.
  • Do give me an Apigee console - or similar - so I can see for myself what's happening.
  • Don't give me absurd key signing requirement - I should be able to call the API from a web browser just by typing stuff in.
  • Do make it as easy as possible for me to get started - get your CEO (or similar) and see how long it takes her to set up an account & launch her first call. If it's more than 5 minute, go back to the drawing board.

Example Code

  • Don't tell me what your API can do - show me a few cool calls to start me off.
  • Just because you love Ruby, doesn't mean everyone does. Show examples in a variety of languages.
  • Provide examples of code which won't work and explain why.
  • Comment your code. It may be obvious to you what "choes=17|L" means, but it may not be to me.


  • This is possibly the most important area.
  • I need to know what I can do, how I can do it, why I should do it a certain way, and what response to expect.
  • For. Every. Single. Function.
  • If you can't document your API, people can't use it.

Full Enumeration of Responses

  • Tell me the full range of response I can expect.
  • A good example is Twitter's "retweet_count", the documentation used to imply that the response would always be an integer. However, it would occasionally respond with a string of "100+". Naturally, this meant developers would write code expecting ints which would fail whenever a string was encountered. If you can't tell me what responses to expect - how can I code something which handles those responses correctly?
  • What error codes are you likely to throw?

Variety of Response Language

  • Yes, you love XML. Guess what? I don't!
  • The customer is always right. If the customer (developer) wants JSON, XML, PHPobject, or just plain text - you should give it to them.
  • It's the API designer's job to make life easy for developers - so reply in whatever formats the developer wants.

Human Readable Response

  • Developers are humans! Yes! It's true! And they can't all pretty-print JSON in their heads. Give them something they can read without resorting to external tools.
  • The Wikipedia API is a brilliant example of this. They have a human readable response for their API calls.
  • Unless you have a very good reason not to - all your responses should be pretty-printed. It helps with debugging and makes life just that little bit easier for a struggling developer.

Human Readable Requests

  • Developers are humans! Yes! It's true! And they can't all remember every little acronym in their heads. Give them something they can read without resorting to documentation.
  • What's easier to remember "gnxID" or "getNextId"?
  • Keep your parameters consistent.


  • Consistency is a virtue. If you have two similar APIs (say, search & read) they should take the same parameters and produce identically formatted responses.
  • If you have to change the way your API responds, or the way it accepts request, that's fine - but use versioning so that developers don't have to update their code if they don't want to.
  • Never deprecate anything! Once an embedded device has had its firmware burned, it's unlikely to ever be updated. If people or services rely on you, it's simply unacceptable to kill something off. Remember, not every developer or end user can update their software.


  • Perhaps the most important of all HCI commandments - Keep It Simple.
  • Don't engage in a needless dance where developers have to take several steps to do a single action.
  • Try to explain what you're doing in a single sentence. If you can't - it's probably too complicated.


  • I'm sure you're very proud that your community has created some libraries - but they're not good enough.
  • Want people to use your API? Provide libraries in a wide variety of languages.
  • Update and support those libraries.

Detailed Errors

  • It's not enough to say an error has occurred. Say why it has occurred.
  • Error codes must always be accompanied by human readable error messages.
  • Do you really need to throw an error? Can your API take a "best" guess at what the user was trying to do? Be generous in what you accept.


  • Your API sucks. Accept that.
  • Provide a mechanism where people can feed back what they think is broken, poorly implemented, missing, or just plain confusing.
  • Discuss the feedback openly. See what the rest of your community thinks.
  • Act on feedback. If a feature request hasn't been acted on after 6 months, you've probably failed.

So What?

There is nothing new in this post to the seasoned developer. But as Matt Gemmell reminded me recently - some people just don't know the basics.

If you're interested in making your API useful for developers, you have to treat it like any other product. You have to consider HCI factors, you have to do product testing, design, and planning.

Your API is a product. Treat your developers as you would your most profitable users.

Further Reading

There are many books on this subject - the two I recommend are:
Basics of the Unix Philosophy (free).
The Design of Everyday Things (paper or ebook).

19 thoughts on “API Design is UI for Developers

  1. says:

    Can't agree more with you.

    We at Mashape.com have a bunch of well designed APIs, with standardized client libraries, examples, errors, and console.

    Happy to get your feedback on it.

  2. says:

    Hi Terence,

    I enjoyed your list, but have a followup question. Coming from the world of startups, I know a ton of companies that have fascinating data available to play with, that they would be open to getting out in the world, but never expose it via an API because they don't have the resources to "do it right". I'd far prefer get a minimal (though still usable) set of things to play with than nothing at all... Do you have an opinion on which pieces of these are necessary for an MVP API? For example, I'd personally bias towards simplicity and clear documentation of parameters and responses, while not caring as much about variety of supported response types or libraries. Thoughts?

    1. A good point. I'd rather have a well documented API which only spits out XML than a poorly documented one which can respond in every language.
      I'd say, very roughly, documentation, read only, multiple formats, read all data, write.

  3. I believe that Web APIs will start a similar usability revolution in API design like Web user interfaces did in user interface design in the late nineties. Until then users were captive audience and had to put up with the GUIs we gave them. The Web liberated them and put an alternate GUI just a mouse click away. And suddenly *everybody* was doing user interface usability studies and reading books like "The Design of Everyday Things". We are almost there with APIs, and posts like this will help make it happen.

  4. says:

    "I should be able to call the API from a web browser just by typing stuff in."

    Ah, you can go much further though - just make it so the same endpoints that you use for your website are the endpoints you use for your API.

    One of these days, just like the Clojureists have done with Lisp, people will realise that the Semantic Web people knew what the fuck they were talking about all along. I fear that path is long and dull though.

  5. Nice post with a great set of very realistic demands that I agree we should be thinking of.

    Thanks for taking the effort to share.


  6. says:

    These things all cost money. I agree that in an ideal world, every api has every one of these traits, but some of them are expensive to make happen, like a well-maintained client library in a wide variety of programming languages.

    Better to just make it so easy to use that people can write the client library themselves more easily than learning how to use someone else's client 🙂

    It's also worth lurking on Stack Overflow and/or setting up your own Q&A site to field questions.

  7. Christophe says:

    Good and informative summary, thanks.

    Your statement about C++ is pretty cheap though, you have to consider the domain(s) of the language. It is complex because it's concepts more closely build on how the hardware actually works and provides tools for those who need access to those deep internals. Considering that most valuable software is still build with C++ also proves it has reason of existence. I believe that knowing how hardware works actually makes you a better software developer. Comparing it to PHP is just wrong..

    1. The PHP/C++ thing has got the most vitriolic reaction from some quarters. They are, as you rightly point out, for completely different fields.

      I would say that an API should be simple and powerful - but I'd rather it was simple & weak rather than hugely complex and powerful.

      If I can't get my head around the basic concepts of your API in 30 minutes, it's probably too complex.

      Thanks for the comment.


  8. JohnIran says:

    What is simple?? What is user friendly?

    Your thoughts about C++ or C show me that you really do not know much about the
    real world.

    C/C++ is meant to do Operational Systems, Programming language, Avionic stuffs, low level stuffs.

    PHP ??? What hell is that? For my world, aviation stuffs, nothing, like any others.

    Be careful, programming language is like love and money, each one has it own game to play.

    What is more important? YES....

    What language is better? YES....

  9. Sloot Plembock says:

    Thought the comments on the Twitter API funny, including the linked article. Expecting an integer... You know its ALL string right. Just because your JSON parser converts to integer is irrelevant, its all chars. I think they put that in there just to make sure you were awake.

  10. I think this post is a great resource for anyone getting started on developing an API.

    As mentioned in other comments, implementing all these features would be a very time consuming task. I would love to see a follow up post listing tools and services that would make implementing some of these aspects quicker.

  11. Thank you so much Terence! Great post. Agreed, I think that sometimes people forget that APIs are an interface, just as important as any GUI - and the developer experience is critical.

Leave a Reply

Your email address will not be published.

%d bloggers like this: