Rant: HTTP status codes

API design matters and it makes your API hard to use when you derail from well established standards.

Please use correct HTTP status codes, It makes your API easy to use.

I have gotten 200 OK response code with HTML error page(from multiple APIs), where API was supposed to always return JSON data.

Now to deal with that I had to do following.

1. check for content-type
2. check for status code
3. try parsing response and handle JSON parse errors

I am fine with writing code that does all this but I shouldn’t need to.

If API used correct status code it can be simplified to following code.

Here i am using success? helper provided by httparty

if response.success?
  # do my thing
else
 # handle failure
end

Rant Over

Further Reading on API experience design

  1. User experience design for APIs by Francois Chollet, Author of Keras(Popular Python Deep Learning library)
  2. How ignoring UX hurts your API and what you can do about it