How to make your APIs better

APIs are everywhere today and can be a great building block of modern applications. But all too often APIs are not truly great. Rather than love your API, developers curse it.”
John Musser
in relation to this slide deck.

Yesterday’s post was about the importance of having an API that’s easy to integrate with for the positive word-of-mouth that it delivers (as opposed to the potentially destructive negative word-of-mouth of a bad API).

John Musser’s slide-deck reveals 10 reasons why developers may hate your API:

  1. Your documentation sucks
  2. Your communication skills need work (you don’t keep your developers informed)
  3. You don’t make it easy (no getting started guide)
  4. Lawyers (commercial restrictions)
  5. Your API is unreliable (or slow, buggy and unreliable)
  6. You don’t give me the tools to succeed
  7. You’re marketing to me, not helping me
  8. Your API is too complicated (and your own customs such as auth, protocols, formats)
  9. Your TTFHW (Time to first “Hello World!”) is too long
  10. You haven’t learned (from the best)

All of these points are relevant. You could probably break this down into the following single fix:

  1. Simplicity – Make interfacing simple for developers through:
    1. Clear, concise documentation (and documentation that is evolving as the interface does, thus meaning the latest versions need to be easily accessible online)
    2. Making tool-kits / code-libraries / SDK (software development kits) readily available and across multiple development platforms
    3. Providing code samples
    4. Providing simple access to keys (if applicable)
    5. Providing simple error / exception handling
    6. Providing agents that are reliable and have admin functionality that make them easy to reinstate
    7. Easily accessible support (tech-assist, blogs, forums)
    8. Well defined road-maps (and functionality sunsets)

We often speak of UX (User Experience) but we seldom talk about DX (Developer Experience). You always hear the vendors spruiking the ease of use for operators of their applications or devices. But how often do you hear vendors speaking of the ease of use for us poor, forgotten OSS integrators?

The reality is that few vendor products work in isolation. They need to connect to other stuff to benefit from the network effect. If your APIs are difficult to use, your products will stay in isolation (discarded or worked around), limiting their ability to contribute value to your customers.

Read the Passionate About OSS Blog for more or Subscribe to the Passionate About OSS Blog by Email

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.