Suggestion from Twitter re. HTTP status. about api-standards HOT 4 OPEN

Expanding here, where I have more than 140 characters:

You write

Error responses should include a common HTTP status code

That seems to indicate that the HTTP status code only has to be in the response text itself. I'd go further (or clarify it, if it's the intent anyway), and require that the response has the appropriate HTTP Status, and not just containing it within the text.

You may also want to not restrict it to just the 200/400/500 codes, as others may be valid as well, for example 405 or 403.

I can make a pull request with my proposed changes if you think that'd be helpful?

from api-standards.

Thanks for your input @colinfrei. Yes, please! Pull requests are definitely welcome!

You may be interested to take a look at page 10 - 12 of the Web API Design document referenced here. (You can download the doc from apigee.com.) This does a pretty good job summarizing our thinking about this section of the specs so far. This guidance sounds pretty solid to me, "Start by using the following 3 [codes: 200, 400, 500]. If you need more, add them. But you shouldn't need to go beyond 8."

If you recommend explicitly adding additional HTTP codes, I'd be interested to know which ones. If there are any particular use cases you have in mind here, it would be helpful to know more about these too.

from api-standards.

@colinfrei Just to clarify for myself what you're saying is that you want the doc to specifically lay out that the HTTP Status code in the body of the response match the HTTP Status in the Response Header?

from api-standards.

Just to invert Twitter's suggestion - this feels like a clear case of trying to solve a problem that doesn't exist. HTTP already tells me that my GET or what have you was "OK" by returning a 200. Why would we occupy bandwidth by sending me back a representation of what the HTTP already told me (by giving it to me in the first place).

That's not metadata - that's meta-meta. Uber meta.

from api-standards.