Making sure your API doesn’t suck

A Phalanger - a type of possum. Awesome.

I’ve recently had the displeasure of working with an API published by one of our service providers. I won’t name names as it’d be a little embarassing, but we provision a lot of something from then and then those somethings are used and the provider records their use. The API exposes both the ability to manage these somethings and the ability to report on their use.

There’s a great REST book by the lovely people at O’Reilly (it has a Phalanger on the cover) which describe the best practices for building a RESTful API. There’s a lot covered in the book and I won’t go into it all here. However, there are some lessons to be learned from the book and from using APIs in general about writing an API, even if it isn’t restful.

Here is a (non-exhaustive) list of things to do to make sure your API doesn’t suck:

  1. Don’t return HTTP 200 OK for EVERY response. If the query to the API fails, send an appropriate response code.
  2. If you are COMPLETELY unable to send different response codes to describe the outcome of the request, make sure you send SOMETHING to the client so they know the status.
  3. Make sure this SOMETHING is documented.
  4. Try and return JUST ONE type of response. If XML, then just send XML. (Bonus tip: Don’t send XML with a plain text header, it’ll annoy your clients).
  5. Don’t send mixed responses. For example; if your documentation states the client can request a CSV, send a CSV, don’t send the error as XML and the CSV as success. If it doesn’t work, send an appropriate HTTP response … oh, right…
  6. Document stuff.
  7. Don’t describe methods in the URL:, param2, paramn) is NOT RESTful (and is stretching the description of API).
  8. Use POST, GET, UPDATE and DELETE properly and in context.
  9. Send API auth credentials with HTTP auth, not in the URL. They can be read in the logs.
  10. Try and make sure that upstream errors are reported faithfully by your API. No point in the API returning OK when the request IT made upstream failed. There’s no confidence in Confidence-Free-Town

There’s probably more, but that’s all I’ve uncovered when working with client APIs. Avoid those 10 items and you’ll be well on your way to writing an API that doesn’t suck!

One thought on “Making sure your API doesn’t suck

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s