Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How to (and how not to) design REST APIs

github.com

Post reply on HN
Print view View original

11–20 of 21 posts

Re: How to (and how not to) design REST APIs

#11

Post by DaiPlusPlus »

jawns wrote: post #7

Regarding the author's recommendation against using 404: The author says it's ambiguous, because it could mean the route is not found, or it could mean the requested item is not found. Some people use 204 to indicate the latter: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 It basically means, "We received and understood your request, but you're not getting a response." And you can infer that it's beca…

But HTTP 204 is also appropriate for a some POST requests where a response is unnecessary or sometimes not even possible (e.g. browser-based "beacon" requests during onunload[1]), so if you use 204 to represent entity-does-not-exist then you need to re-think how to handle no-response-responses.

As an alternative to using HTTP 404 for detecting a misconfigured server with bad routing, you could use the "Server" response header to include an invariant indicator as a confidence sign to the client that the HTTP 404 response does not mean bad-routing or misconfigured server - or expired-domain-name-now-points-to-a-domain-squatting-website.

[1] https://developer.mozilla.org/en-US/docs/Web/API/Navigator/s...

Re: How to (and how not to) design REST APIs

#12

Post by treve »

jawns wrote: post #7

Regarding the author's recommendation against using 404: The author says it's ambiguous, because it could mean the route is not found, or it could mean the requested item is not found. Some people use 204 to indicate the latter: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 It basically means, "We received and understood your request, but you're not getting a response." And you can infer that it's beca…

If it worked for you, that's fine... but this is completely counter to how most HTTP applications work and definitely not a best practice. Both returning errors or the interpretation of the meaning of 204.

The author at least suggests using 400, which at the very least will make clients and proxies behave in a predictable way, but ideally you just return the appropriate HTTP status code, and use a well-defined response body to indicate why the specific error was returned.

Re: How to (and how not to) design REST APIs

#13

Post by vsnf »

jawns wrote: post #7

Regarding the author's recommendation against using 404: The author says it's ambiguous, because it could mean the route is not found, or it could mean the requested item is not found. Some people use 204 to indicate the latter: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 It basically means, "We received and understood your request, but you're not getting a response." And you can infer that it's beca…

> At a previous company, we returned a 200 for anything that was not a true HTTP error on our side

I work at a company that does this and it is beyond annoying. We've had multiple discussions between the dev team and we chalk it up the difference between application developers, who want the error codes to reflect the state of the application, and network engineers, who want the error codes to reflect the state of the network. Both sides have merit, but as an app developer I really hate the networking engineer approach to this.

Re: How to (and how not to) design REST APIs

#14

Post by [deleted] »

jawns wrote: post #7

Regarding the author's recommendation against using 404: The author says it's ambiguous, because it could mean the route is not found, or it could mean the requested item is not found. Some people use 204 to indicate the latter: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 It basically means, "We received and understood your request, but you're not getting a response." And you can infer that it's beca…

[deleted]

Re: How to (and how not to) design REST APIs

#15

Post by brongondwana »

I would extend Rule 6 much more into Rule 7 - if you're returning an id which is numeric, prefix it with a non-number, so it won't get accidentally converted to a number. This has been a particular pain with Perl (yes, it's still used in place) JSON libraries, where knowing if you're going to serialise to a string or a number is quite dependent on how the variable has been touched - so things like stringifying it in a debug line might change the output.

If you make it so your ID is never something that Excel can incorrectly assume is a date, you're making life better for everybody.

Re: How to (and how not to) design REST APIs

#16

Post by jacknews »

LAC-Tech wrote: post #9
jacknews wrote: post #6

"Rule #1: DO use plural nouns for collections" I disagree, as you then have to deal with English pluralization rules to match single objects and collections. Also database tables should just be singular, things like 'country.id' makes more sense than 'countries.id'. Also no discussion of versioning?

English pluralisation rules are a non issue. 1.5 billion people world wide speak English, and I'll forgive some of them if they accidentally make a gooses URL instead of a geese one.

Why have plural at all. All rest urls except index, which is easily discernible because it has no id, make more sense in the singular:

  get /ticket/12
  patch /ticket/12
  put /ticket
The problem is not humans getting confused by 'gooses', but that sometimes your code has to do the mapping, and there are plenty of edge-cases. Just avoid the issue entirely by sticking with singular throughout.

Re: How to (and how not to) design REST APIs

#17

Post by Noishe »

hcrean wrote: post #10
tshaddox wrote: post #2

I read the part about not using 404s twice and I still don’t quite get it. It sounds like the author was using some infrastructure separate from their actual app server that unpredictably returned 404 responses and thus they don’t want to deliberately return 404 responses?

They are attempting to argue that 404 is ambiguous, so we should avoid it. They do not to my eyes meaningfully highlight a replacement outside of some very specific cases. I strongly disagree with this stance as I don't think 404 is ambiguous at all. Although it would be useful to know at what point in the broader hierarchy of a specific resource requested the unavailability starts: Ultimately 404 just means the spec…

The thing about 404, is that you can both return 404 as well as an error document that has the structure the author is looking for, which means there is no reason why you can't return a 404 status.

Got 404, returned body is json, returned body is an error object, good to go.

Oh and, by returning a 404 you help intermediate caches know that they should not cache the response.

Re: How to (and how not to) design REST APIs

#19

Post by manvillej »

hcrean wrote: post #10
tshaddox wrote: post #2

I read the part about not using 404s twice and I still don’t quite get it. It sounds like the author was using some infrastructure separate from their actual app server that unpredictably returned 404 responses and thus they don’t want to deliberately return 404 responses?

They are attempting to argue that 404 is ambiguous, so we should avoid it. They do not to my eyes meaningfully highlight a replacement outside of some very specific cases. I strongly disagree with this stance as I don't think 404 is ambiguous at all. Although it would be useful to know at what point in the broader hierarchy of a specific resource requested the unavailability starts: Ultimately 404 just means the spec…

without 404, how will I force my collection of funny 404 images onto the world: https://tenor.com/view/dog-moon-moonlanding-landing-nasa-gif...

Re: How to (and how not to) design REST APIs

#20

Post by jakobson14 »

jawns wrote: post #7

Regarding the author's recommendation against using 404: The author says it's ambiguous, because it could mean the route is not found, or it could mean the requested item is not found. Some people use 204 to indicate the latter: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 It basically means, "We received and understood your request, but you're not getting a response." And you can infer that it's beca…

Have you not heard of 500 errors? How about 400 for "bad request"?

Seriously, stop reinventing what is already an established standard. There is nothing more annoying than a server that returns a 200-class status when the thing I requested is not in the response.

Post reply on HN