API Pet Peeves

Things that shouldn't be done

I've been doing a lot of work recently using various APIs, including creating some myself, and I've noticed quite a few seem to have annoying traits.

I mainly work with REST APIs, so this post will focus on them; although most of the points can be transferred across to others.

I don't claim to be an expert in REST APIs, far from it, but here are some things that really annoy me. As usual, if I've got anything wrong, or if there is a better way to go about it, let me know in the comments!

The Gripes

Lack of Documentation

The whole point of exposing your site to developers is to allow them to create applications using your data/services. Not telling them how to do that is a massive drawback.

We shouldn't have to guess what a method returns, or what parameters it takes.


All of your methods and variables should follow a convention, and should stick to that convention no matter what.

If, a few months down the line, you decide you prefer camelCase to underscores, don't start writing new methods in camelCase, stick to underscores. There's nothing worse than calling /example_method then calling /anotherExampleMethod.

Only change the convention for a new major version of the API, and even then keep the old version for a while.

Return Something Sensible

If I make a request in JSON, I'd probably like it back in JSON (unless specified in the request). Don't just automatically return XML; either give me a choice or return in the same format I initially used.

If returning an error, return a machine readable error, not an an error for a human. Don't return a nice html page with the error explained, give me a JSON packet with an error code and description. Also, please return a header code. Don't return every request with a 200!

Use HTTP Verbs

Use the HTTP verbs to keep your URLs clean and logical, don't prefix your methods (e.g., post_user/delete_user). This allows the url /user/44 to be used for multiple things. Sending a GET request will retrieve the user whereas sending a DELETE request will delete the user for example.

Standardise Your Returns

One API I'm currently working with does this, and it creates a lot of extra code. When returning a list of items (users for example), return the same format list even if you're returning 0, 1 or 100. Don't return a single object for 1, and an array of objects for 100; return an array for any amount. That way, all I have to do it count the items in the array, and I can loop through it no matter what.

I've probably missed some...

I've probably missed some obvious gripes, but they are the ones that have been bugging me lately.

If you can think of any I have missed, let me know!

Want to let me know what you think of API Pet Peeves? Why not leave a comment, follow me on Twitter , or !


comments powered by Disqus