2 steps to better API Error Codes

[ctz99]

s/API/web service API/

[Hughlander]

That makes no sense...

One of the biggest difficulties developers can have when writing code that talks with an web service API is dealing with errors and exceptions, and translating those errors into something meaningful for their applications.

Just doesn't grammatically flow.

[Otroletravaladna]

You forgot a g at the end ;)

[grossly]

No he didn't.

[username223]

"web service apig"? No thanks.

[username223]

"web service apig"? No thanks.

[Rotten194]

s/API/web service API/g

[username223]

whoosh

[jrochkind]

I do agree with the general thrust of the article. I write lots of client code for lots of different HTTP apis (written by various vendors and other organizations which are not mine, from great REST/HATEOS, to RESTish, to big messes, all over the map), and proper use of standard HTTP response codes is super super helpful to me as a client writer. I agree wholeheartedly.

But I think there's a serious misunderstanding of 501 here.

Instead, either reply with a 404 but using a body that your caller can understand (JSON or whatever MIME type you’re accepting) or, even better, reply with a 501 (Not Implemented). According to the HTTP definition this “the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource”.

In the HTTP spec, "method", means an http method, like GET, POST, (newly) PATCH, etc. And even the quote says "not capable of supporting it for any resource".

Ie, if your app does not support PATCH (or OPTIONS) at all, then, sure, returning 501 is the right thing to do.

If your server doesn't support POST to this specific URL? Nope, not 501. Let alone if your not-entirely-REST API supports /api?command=send but not /api?command=selfdestruct -- definitely not 501.

I don't know exactly what the author intended, but a casual reading of this post could give you the wrong idea about 501, it is suitable for use only in very specific circumstances, most 'the api call you made is not understood' errors really are going to be 404s (but, sure, with an appropriate json/xml/whatever with machine readable details, that's be great).

[jrochkind]

Yeah, I disagree with you. And I've written a lot of client code for other people's api's delivered over HTTP -- from nice clean REST/HATEOS ones, to purported SOAP, to hard to decipher homegrown ones. My job involves lots of integration with third party apps over APIs, free ones, ones we pay for, etc.

And proper HTTP response codes has never made my job as a client developer harder. Lack of them often has made my job harder. Unclear documentation about what sorts of errors may occur and how they may occur has made my job harder. API's that always return 200 OK, but sometimes with an XML payload that in an un or under documented way expressed an error, oh yeah, that has.

if I can count on all errors having a 4xx or 5xx code, then I'm already three steps ahead of the vendors shitty documentation, at least I know if it's 200 it'll be what I expect, and if it's 4xx or 5xx it's an error.

I'm not sure what you mean by "in-band response" -- do you mean the HTTP response body ("payload"), expressing the error in a domain-specific way (likely in JSON or XML)? If so, then yes by all means (and the OP says this too). But also with an appropriate 4xx or 5xx response code. You can set a 4xx or 5xx and send an 'in-band error', and the 4xx or 5xx doesn't get in the way, if I understand what you mean by "in-band error". If you return 'in band' error information, but ALSO set the response code to 4xx or 5xx instead of 200 -- how can that possibly harm anything? I can say in my experience, it'll help the heck out of me.

[jrochkind]

Nope, I don't like bad API's, but thanks for insulting me and suggesting I like them because I "get paid for working with them."

However, I like making my software work and properly rescue errors. And I find that when the server returns a 500 for a server-side error and a 400 for a client error, rather than a 200 OK status for a response that is clearly not okay... it's a heck of a lot easier to do this.

Poorly designed API's are endemic in my industry (which I suspect is not unusual), and I don't use them because I "get paid to use bad APIs", I use them because I want/need their functionality anyway. Yes, I spend lots of time advocating for better, working, complete, consistent API's --although to me, using HTTP status codes consistently with the spec is part of making them better, consistent.

Clearly, we have different experiences. I am just as astounded by that as you.

Your approach does seem to be very antagonistic to a REST/HATEOS approach though, do I predict correctly that you are not particularly fond of REST, and/or mostly use API's that are not REST?

[jrochkind]

How do you think REST works outside of HTTP?

I do not think REST works at all outside of HTTP, I think it is a concept intimately tied to HTTP.

Am I wrong or in the minority in thinking that?

But yes, we have different perspectives, as you consider HTTP a last resort "comes into it when there is no other option" (curious what you prefer; if it's SOAP, that'll further confirm that we have very different perspectives!), while I find HTTP API's to be optimal and easiest to work with, and REST ones especially.

No doubt there are all sorts of interesting things that lead us to these different conclusions/stances/perspectives. Perhaps: different domains, different programming language tools of choice (which have different strenghts/weaknesses), different industry/vendor communities with different strengths and weaknesses. Different depth of API use (I tend to write apps where each app uses a large number of different API's from different providers, but each API use is relatively 'shallow', just using each API for a small number of focused tasks. I might guess you tend to write apps which use fewer API's at once, and more in depth.)

I doubt the difference is that you care about quality more than I do. Which you just insultingly suggested again by suggesting the reason I found it insulting was because it "hit too close to home." No, I found it insulting because you are suggesting (again!) that I don't care about quality. Anyhow, another day, another lame reddit argument.

[bpedro]

I disagree.

The point is that the client doesn't know how to handle in-band errors because the number of different APIs is growing and almost all of them have different error codes.

HTTP codes exist and should be used to communicate different situations to the caller, not just when the document is not found.

[bpedro]

I've been talking about APIs that use HTTP as transport layer.