How to (and how not to) design REST APIs
github.com
How to (and how not to) design REST APIs
1–10 of 21 posts
Re: How to (and how not to) design REST APIs
#2I 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?
Re: How to (and how not to) design REST APIs
#3I get extremely annoyed when an API getting one thing has a plural and an API getting many things has a singular.
Re: How to (and how not to) design REST APIs
#4I 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?
Some infrastructure like that might exist on the server end; load balancers, etc.
I took it to mean 404 should mean you haven't hit the API at all.
Re: How to (and how not to) design REST APIs
#5I 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?
Not the author, but I think the idea is to avoid overloading the meaning of 404. They argue 404 should mean the request didn't match a known route, in case the request is recognized but the record itself isn't found you should return a different 4xx code
I kind of get this and wouldn't complain about an API doing this, but I also wouldn't be surprised for `/api/v1/posts/abc-123` to return 404 because the route handler couldn't match the post ID.
Re: How to (and how not to) design REST APIs
#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?
Re: How to (and how not to) design REST APIs
#7Regarding 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 because the content you requested is not there.
At a previous company, we returned a 200 for anything that was not a true HTTP error on our side, with a dedicated error message in the response for anything else. So, for instance, instead of returning a 403 when the API user provided invalid data, we would return a 200, indicating that we successfully did everything we were supposed to do, but then explained in the response what invalid data needed to be corrected.
I liked that approach. Anything non-200-level meant that we screwed up. And any 200-level response with an error message meant that the user screwed up.
Re: How to (and how not to) design REST APIs
#8"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?
It would be countries[i].id (or country.id in a forEach)
Re: How to (and how not to) design REST APIs
#9"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.
Re: How to (and how not to) design REST APIs
#10I 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 specific 'tip of the spear' resource requested is not found.