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.
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.
- check for content-type
- check for status code
- 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
Relevant xkcd because there’s one for almost everything
Further Reading on API experience design
- User experience design for APIs by Francois Chollet, Author of Keras(Popular Python Deep Learning library)
- How ignoring UX hurts your API and what you can do about it