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 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.

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?

The author should keep the examples consistent, it was showing good example first then bad examples then all of a sudden it swapped to bad example first then good which goes against his Rule #9.

I get extremely annoyed when an API getting one thing has a plural and an API getting many things has a singular.

"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?

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.