Many of your examples are changing the query string, not the resource path. That's an important designation in REST semantics. REST APIs shouldn't use query strings for accessing singular records with IDs, that's what direct resource paths are for. Anything accessed with a query string should be treated as a search.

/api/v1/employees/100 - direct path to a resource. 404 if it doesn't exist.

/some_photo.jpg - direct path to a file/resource. 404 if it doesn't exist.

/photo/100 - direct path to resource: photo ID 100. 404 if it doesn't exist.

/photo?id=100 - search for a photo with ID "100". Return a code 200 with an empty results set if that ID is not found. (With optional application-specific error feedback in the response body.) 404 if /photo doesn't exist at all.

The spec says:

>The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.

So when you say:

>yet the record doesn't exist, then the resource doesn't exist.

So you do have a current representation for the target resource. Namely, that it doesn't exist.

> So you do have a current representation for the target resource.

No.

> Namely, that it doesn’t exist.

That it isn’t a representation, it is a fact about the universe (not the resource, because existence is not a predicate) which is inconsistent with their being a representation. A resource must exist to have a representation.

Yes, and sending a 404 status code is the correct and succinct way of expressing that fact.

404 says you didn't find it. Not that it doesn't exist.

> 404 says you didn’t find it. Not that it doesn’t exist.

Since a resource that does not exist cannot have any representation, it is therefore impossible for a representation to be found of such a resource. In fact, other than in the case where 421 is the correct response (“don’t ask me, I’m not responsible for that URL”) or where 406 is a more specific response than 404 (“I have the resource requested, but can’t produce a representation in the format you have requested, and don’t want to waste both of our time sending you a format you may not be able to use”), the only reason for a 404 is that the resource does not exist.

Exactly, my thought as well. Particularly, from QA perspective (automation or performance testing), testers often assume `200` means everything is fine; let's move on. But in reality, it is not.

Api calls and document requests are very different. the latter are primarily interpreted by CDNs and browsers and need to work for them; the former are called by code and handled by code.

For me it boils down to this:

If you ask for an employee that doesn't exist, is it a failure? Or is it just a negative, but expected response?

Perhaps that's a stupid question though.

If you write an API designed to return a single entity matching the path provided, it's absolutely an error if it doesn't exist. If your API returns the simplest possible JSON representation in a success case, what JSON should it return if it doesn't exist?