A best practice to handle HTTP status codes which are unexpected but 2xx?

[Donghwan Kim]

Hi,

I'm going to use 200, 400, 401, 403, 404 and 500 status codes only and regard all the rest as error because they are not expected. If some new status code like 409 should be added, I think the version of API I'm writing should be incremented for that or with some new endpoints.

Here the problem is 2xx e.g. 201 is an error according to API I'm writing because it is unexpected but is not an error according to HTTP status codes, but the API is built on HTTP for sure. 

I'm inclined to regard it as an error because API server is not supposed to return such codes but would like to hear your opinions. Is it safe to regard all the unexpected status codes error or is too ideal?

Thanks,

-- Donghwan

[Jørn Wildt]

This sounds like a bad idea to me. If its a HTTP based API then you should embrace HTTP and use all the status codes available to you.

For instance - you have not mentioned the 30X codes for redirects, would you really consider it an error to make a redirect? I certainly would not.

So, use all the codes - they are there for a reason (well, maybe not the "I am a teapot" code). Do not change semantics such that 30X suddenly becomes an error code - it will break client libraries and make life misserable for client devs.

Regards, Jørn

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

--
/Jørn

[darrel...@gmail.com]

Hi Donghwan,

There are at least three reasons why an API should not define “expected” HTTP status codes from an API.

• Returned status codes are not always generated by your API code.  A web server may generate 502, 411, 413, 431, 414,417 (and others) without your API code ever being reached.  An intermediary component (load balancer, cache, proxy) could return 502, 504, 511, 408 without the request even reaching your API server.  This makes it virtually impossible to define an accurate subset of HTTP status codes for any client on the Internet.
• Just because your API doesn't return a status code today, doesn't mean that you might not want to return it tomorrow.  Consider redirects (300, 301,302, 303,307,308), responses to conditional requests (304), support for long running transactions (402), responses from CDNs (203).  Encouraging client developers to build clients that will break if a new status code is introduced is not only contrary to the spirit of the web, it is also an explicit violation of the HTTP specification.
• The HTTP specification already defines what a client application MUST do if it receives a status code that it does not recognize:

From RFC 7231: “HTTP status codes are extensible. HTTP clients are not required to understand the meaning of all registered status codes, though such understanding is obviously desirable. However, a client MUST understand the class of any status code, as indicated by the first digit, and treat an unrecognized status code as being equivalent to the x00 status code of that class, with the exception that a recipient MUST NOT cache a response with an unrecognized status code.”

https://tools.ietf.org/html/rfc7231#section-6

This means that a client developer must write client code to deal with 400 and 500 errors and can choose to use that same code to deal with any 4XX error or 5XX error.  However, you should not treat an unknown status code as an error in itself.

Regards,

Darrel

--

[Donghwan Kim]

Hi Darrel,

I was under the impression that I should provide default response which handles 'unexpected' HTTP status codes because Swagger, http://swagger.io, provides such functionality. If you go to http://editor.swagger.io/#/, you can see all operations of the default example regard all HTTP status codes except 200 as an unexpected error.

Anyway now I learned API should embrace (or may even specialize for our own purpose) HTTP's semantics but should not deviate from there.

Thanks!

-- Donghwan