Rant - Your API is broken

on rant and REST-APIs

API design matters and an API becomes hard to use when you derail from well established standards.

TL:DR; - Please use correct HTTP status codes & content type, It makes your API easy to use.

Rant Start

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

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 :angry:. 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

Relevant xkcd because there’s one for almost everything xkcd

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

Continue Reading