Is the description component of a HTTP status code used? For example, in the HTTP response '200 OK', is the OK (i.e. the description) ever used? Or is it just for humans to read?
No, the "reason phrase" is purely there for humans to read. Nothing should be using it programmatically - especially because in HTTP/2, it's been eliminated:
HTTP/2 does not define a way to carry the version or reason phrase that is included in an HTTP/1.1 status line.
The status code is often used. For example, if you are using AJAX, you will most likely check the HTTP status code before using the data returned.
However the description is just for humans as computers recognize the status code and what it entails without the description.
The description is a standard message associated with the code itself to get a quick description of the code. It is used for a diagnostic, along with its full description wich can be found on the https status code list. So, it is not "used" as i think you're implying, but indeed only used for diagnostic by humans
The data sections of messages Error, Forward and redirection responses may be used to contain human-readable diagnostic information.
Related
Let's say we have an API with a route /foo/<id> that represents an instance of an object like this:
class Foo:
bar: Optional[Bar]
name: str
...
class Bar:
...
(Example in Python just because it's convenient, this is about the HTTP layer rather than the application logic.)
We want to expose full serialized Foo instances (which may have many other attributes) under /foo/<id>, but, for the sake of efficiency, we also want to expose /foo/<id>/bar to give us just the .bar attribute of the given Foo.
It feels strange to me to use 404 as the status response when bar is None here, since that's the same status code you'd get if you requested some arbitrarily incorrect route like /random/gibberish, too; if we were to have automatic handling of 404 status in our client-side layer, it would be misinterpreting this with likely explanations such as "we forgot to log in" or "the client-side URL routing was wrong".
However, 200 with a response-body of null (if we're serializing using JSON) feels odd as well, because the presence or absence of the entity at the given endpoint is usually communicated via a status rather than in-line in the body. Would 204 with an empty response-body be the right thing to say here? Is a 404 the right way to go, and if so, what's the right way for the server to communicate nuances like "but that was a totally expected and correct route" or "actually the foo-ID you specified was incorrect, this isn't missing because the attribute was un-set".
What are the advantages and disadvantages of representing the missing-ness of this attribute in different ways?
I wonder if you could more clearly articulate why a 200 with a null response body is odd. I think it communicates exactly what you want, as long as you're not trying to differentiate between a given Foo not having a bar (e.g. Foo.has_key?(bar)) and Foo having a bar explicitly set to null.
Of 404, https://developer.mozilla.com says,
In an API, this can also mean that the endpoint is valid but the resource itself does not exist.
so I think it's acceptable. 204 doesn't strike me as particularly outlandish in this situation, but is more commonly associated (IME, at least) with DELETEs (and occasionally PUTs/POSTs that don't return results.)
I also struggle a lot with this because:
404 can point to a non existent url, or a path that is acceptable
but the particular referenced resource does not exist. I have also
used it to error out on request body's that carry identifiers that
are non existent.
A lot of people shoe-horn these errors into the bad request (400)
error code which is somewhat acceptable but also a cop out.
(Literally anything the server did not process successfully can be classified as a bad request, if you
think about it)
With 2(above) in mind, a 400 with some helpful message body is
sometimes used to wash out the guilt of not committing outrightly to
a 404, but this demands some parsing expectations on the client's
side, which is not always nice. Also returning a 400 which,
according to this is kind of gaslighting the client, because 400
errors are supposed to be the client's fault entirely with regard to the structure of the request, not because the client asked for something not in your db.
400 Bad Request response status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
The general feeling is that 200 means all is good, and therefore
there's always a tacit expectation the response will always contain
some form of body, not null.(Right??) I wouldn't encourage using a 200 for
these situations. While 204's don't carry the responsibility having to carry a response body, they also sort of convey the message that "something worked", which is not the message you want to send here, right?
What I'm trying to say? Thoughtful API design is hard.
I would like to know if there is a relevant http response header for the 'server generation time' ?
a delta time in ms : time taken between query reception and response send.
Following this wp page I was unable to find it..
for example : 'X-Generation-time' ?
There are no standardized header fields for that. There are probably plenty of private use names that aren't widely used or understood though. Feel free to make up your own unless you think that you might need something that other software might produce or consume.
I have been playing around with parsing HTTP in user-space and I see with some research that there are several ways to send data following the HTTP header and \r\n\r\n. Obviously, content-length is not always used, so what are the other methods and how do you determine the size of the data being sent before hand if not streaming?
I did see content-encoding, chunking and so on, I'm just a bit lost with the overall dynamicness of the protocol in this case. What is the sure fire way of determining the amount of data to be sent (when obviously not streaming something never ending)?
Really appreciate the help.
The new HTTP spec describes this in http://greenbytes.de/tech/webdav/draft-ietf-httpbis-p1-messaging-26.html#message.body.
I have written a mini-minimalist http server prototype ( heavily inspired by boost asio examples ), and for the moment I haven't put any http header in the server response, only the html string content. Surprisingly it works just fine.
In that question the OP wonders about necessary fields in the http response, and one of the comments states that they may not be really important from the server side.
I have not tried yet to respond binary image files, or gzip compressed file for the moment, in which cases I suppose it is mandatory to have a http header.
But for text only responses (html, css, and xml outputs), would it be ok never to include the http header in my server responses ? What are the risks / errors possible ?
At a minimum, you must provide a header with a status line and a date.
As someone who has written many protocol parsers, I am begging you, on my digital metaphoric knees, please oh please oh please don't just totally ignore the specification just because your favorite browser lets you get away with it.
It is perfectly fine to create a program that is minimally functional, as long as the data it produces is correct. This should not be a major burden, since all you have to do is add three lines to the start of your response. And one of those lines is blank! Please take a few minutes to write the two glorious line of code that will bring your response data into line with the spec.
The headers you really should supply are:
the status line (required)
a date header (required)
content-type (highly recommended)
content-length (highly recommended), unless you're using chunked encoding
if you're returning HTTP/1.1 status lines, and you're not providing a valid content-length or using chunked encoding, then add Connection: close to your headers
the blank line to separate header from body (required)
You can choose not to send a content-type with the response, but you have to understand that the client might not know what to do with the data. The client has to guess what kind of data it is. A browser might decide to treat it as a downloaded file instead of displaying it. An automated process (someone's bash/curl script) might reasonably decide that the data isn't of the expected type so it should be thrown away.
From the HTTP/1.1 Specification section 3.1.1.5. Content-Type:
A sender that generates a message containing a payload body SHOULD
generate a Content-Type header field in that message unless the
intended media type of the enclosed representation is unknown to the
sender. If a Content-Type header field is not present, the recipient
MAY either assume a media type of "application/octet-stream"
([RFC2046], Section 4.5.1) or examine the data to determine its type.
This is a somewhat simple question, but sadly I have not been able to find a concrete answer thus far.
We are constructing an API (we're not in production yet) which returns a large amount of data after user authentication, etc. The API system tracks the user's usage on a per second and per hour basis. When the user exceeds either of those limitations, the server returns no content and some http error code.
Presently, I'm using 406 Not Acceptable, but I don't believe that's the best code to use. Its been suggested that 509 Bandwidth Limit Exceeded would be a good one, but I wonder if there is a code which would be considered best practice for my situation. Thank you in advance for your help!
Status code 429 comes to mind:
RFC 6585, section 4: 429 Too Many Requests
The 429 status code indicates that the user has sent too many
requests in a given amount of time ("rate limiting").
The response representations SHOULD include details explaining the
condition, and MAY include a Retry-After header indicating how long
to wait before making a new request.
Well, since you've found no applicable error code, I'd guess there isn't one. In this situation, if I were you, I'd use stick with your 406 or anything like that, just decide on something and keep using it. The browser doesn't care anyway and the API's are used by people that will accept whatever code you return and deduce it's a rule - "if I exceed the usage, I get 406". I think it doesn't really matter what the magic number is.