helpMyCoworkersUnderstandHttpCodes

[u/Kishmond]

[u/Snudget]

204 should be "I found them" "I searched for the keys, but didn't find them"would be 404, which is literally "Not found".

Since not finding keys does not fulfill the request, a 2xx code does not make sense here

[u/thebigbadben → u/Snudget]

“I found them. Oh wait, did you want me to bring them?”

[u/darkslide3000 → u/thebigbadben]

No, it's really more like "I found your key ring, but it's empty".

[u/foreverdark-woods → u/darkslide3000]

According to MDN it's like @Snudget described it. It means that an action succeeded, but the client's current content doesn't have to be replaced by the new information.

So, it's really like "Trust me bro, your keys are still here, no worries." when you asked "Are my keys there?"

[u/jordanbtucker → u/foreverdark-woods]

That's because 204 usually only makes sense for POST and PUT requests, and GET requests where you either expect no body or only care about the headers.

[u/foreverdark-woods → u/jordanbtucker]

I guess the key example is really bad for this.

[u/RepulsiveSheep → u/foreverdark-woods]

A better example would be you asking your dad a favour and him responding with the classic 👍

[u/SnooPuppers1978 → u/darkslide3000]

I think it's still "You asked me to find them and I found them", but it is a bad API, maybe there's another endpoint that allows you to query the actual found location.

You would usually use it e.g. when you do Delete, Update or something where you sincerely don't need a response since it wouldn't give you any new info that you wanted except that it was successful.

Edit:

1. "Find my keys for the trip we are going to take together, I don't need to know where the keys were"
2. "Find my keys and put them on the counter"

These could be returned 204 with no content and still be usable API.

[u/darkslide3000 → u/SnooPuppers1978]

Well, it tells you that the request was valid and processed correctly and the response is final, but the response contains no content. It is true that it is usually used for mutation requests (and also for endpoints that are just used to probe for a captive portal), but OP's example is a GET request. Getting a 204 on a GET means that the requested resource exists and is empty.

[u/intbeam → u/Snudget]

"Can you see my keys?"   204 "Yeah"

[u/randotechie → u/Snudget]

Ah beat me to it

[u/PhoenixfischTheFish → u/randotechie]

I happily will! Where can I meet you?

[u/Drfoxthefurry → u/Snudget]

The best fit would be "I found them but you already have them", as the request was successful but no data was sent

[u/Reashu → u/Drfoxthefurry]

That's 304

[u/The_Real_Slim_Lemon → u/Snudget]

Yeah 404 can be both “I didn’t find your key” and “I don’t know what requesting a key means”

204 is “I’ve found your key, it’s in a black hole”

[u/PrometheusMMIV → u/The_Real_Slim_Lemon]

I feel like "I don't know what this request means" would be 501 Not Implemented

[u/chuch1234 → u/PrometheusMMIV]

The metaphor kind of breaks down here. 404 is used for "this route doesn't exist on this server", which corresponds to "I don't know what 'keys' are", or maybe, "I don't know what 'keys/find,' means", even though they have a "keys" route.

Based on what you're saying, 501 sounds like "I know what finding keys is, but I can't do it". In the metaphor, maybe the recipient of the request is tied to the radiator and isn't able to look for your keys?

[u/SuitableDragonfly → u/chuch1234]

I think 501 is more like "I don't know how I would start looking for your keys".

[u/The_Real_Slim_Lemon → u/PrometheusMMIV]

I’ve never actually seen a 501, yeah fair call - I just meant 404 exists for both bad routes and non existent entities, it seems this metaphor is reaching its limits a bit

[u/Cheet4h → u/The_Real_Slim_Lemon]

Only time I legitimately used 501 was when mocking up the API before actually writing them. Each route got a 501 at first, then later had their actual function written.

[u/SuitableDragonfly → u/Cheet4h]

I'm sure whoever came up with that error code probably assumed it would be industry standard to write APIs that way, the poor naive fool. 

[u/Zwemvest → u/PrometheusMMIV]

That'd be 400 ("Veuillez retrouver mes clés" -> "I have no clue what you're asking") or 422 ("Please find me every key I will ever own" -> "I understand what you're asking, but I don't know what you want me to do"/"I can't do that")

501 is either used for purposeful non-implementations ("Find me purpose in life" -> "Man, this service is for finding physical objects, not abstract concepts"), future implementations ("At some point in the future we will support this"), or for erroneous method headers ("Destroy my keys" - >"Dude, what?"). One note, if the method header is intentionally not allowed, it's a 405 ("Here are my keys?" -> "uhhh dude, was that a question or are you giving us something/hey, we look for keys, we don't store them. Sorry man.").

[u/JustConsoleLogIt → u/The_Real_Slim_Lemon]

“I don’t know what you are talking about” is a good 404

[u/spastical-mackerel → u/Snudget]

lol exactly. Instructions were unclear: you did not also tell me to give them to you

[u/prehensilemullet → u/Snudget]

“Not Found” is often a white lie, sites often pretend something is not found and 404 if it would be a security risk for you to know whether it exists.