Indeed. The application contemplated by HTTP is hypertext. If we are being sticklers for the RFCs, modern applications implementing non-hypertext business logic via HTTP are abusing more than just response status codes.

But if we relax the “hypertext” presumption a bit and consider HTTP a protocol for the transfer of resources, surely an API can be implemented such that using response codes is sensible and useful. REST and SOAP for CRUD operations can still work just fine, and response codes can still make sense in the context of the API itself, even if the content is JSON describing business logic state.

It’s a messy world, so we have to be liberal in what we accept, but using status codes is not inherently abuse. Any ambiguity might just be a symptom of leaky abstractions in the API.

In this context you would also have to include discoverability of URLs.

In this philosophy you would not suppose how employees are named and would ask for a list of valid employees URLs to a URL previously returned by `/api/v1/`.

In this way you only ever call URLs that the api provided you with, so that you are not expected to find out by trial and error whether `/api/v1/employees/100` exists or not; the api itself has already told you this and a 404 is the response to trying to build your own URLs by hand.

>non-existent `/api/v1/employees/100` path

But the path does exist. The employee record represented by that path doesn't exist.

No, the resource /api/v1/employees/100 does not exist.

Yes, and so we return 200 + the current representation of the resource, i.e. it does not exist.

And 404 is the appropriate response code for a resource that was not found at the path requested.

I guess in a pedantic sense, all possible paths “exist.”

No, paths that reach a server and get processed exist.

Define "processed"?

A request with a path that reaches a server, is looked up in the routing table or filesystem, resulting in no resources found, is expected to return "404 Not Found".

You can say the path "exists", but only as a label. All labels can exist. Only a subset of these are semantically valid resource locator paths, and only a further subset reference objects that exist.

Colloquially, https://news.ycombinator.com/this/path/does/not/exist (path "/this/path/does/not/exist") "does not exist" because we're talking about the requested resource.

Of course the path exists, I just wrote it and it's semantically valid.

That's not an interesting question though, and if API responses were this shallow -- just a "semantic correctness checker" -- then response codes would be useless.

>Define "processed"?

Why? We all know what it means.

>Colloquially, https://news.ycombinator.com/this/path/does/not/exist (path "/this/path/does/not/exist") "does not exist" because we're talking about the requested resource.

That path is 404 - Not found and returns "Unknown"

https://news.ycombinator.com/item?id=52081900

Returns 200 - No such item.

In 10 years when we have that many threads it will return content.

As I've said in several other places it depends what you want to tell the client. 404 if you want to tell them you didn't find the resource. 200 if you want to tell them the resource doesn't exist.

I did not mean to hold up HN as a measure of correctness, and I suggest that it is not a good idea to do so.

> 404 if you want to tell them you didn't find the resource. 200 if you want to tell them the resource doesn't exist.

404 is a client error, like all 4xx codes. The requester can correct their request. It does not indicate that the server ~"tried to find but may have overlooked" a resource, it means that the server can authoritatively state that the resource is not findable.

This is essentially, "does not exist at this time". Resources that do not exist today, might exist in the future, or they might not. This is true for both /users/1000 and /some/other/path.

I interpret the RFC to support my belief:

  6.5.4.  404 Not Found

   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.  A 404 status code does not
   indicate whether this lack of representation is temporary or
   permanent; the 410 (Gone) status code is preferred over 404 if the
   origin server knows, presumably through some configurable means, that
   the condition is likely to be permanent.

>I interpret the RFC to support my belief:

Impressive given that it explicitly contradicts your point:

>the server can authoritatively state that the resource is not findable

>origin server did not find a current representation

Those two are not the same thing.

It does not contradict my point at all.

Those two phrases do not lexically parse in identical ways, but we should not interpret the RFC to be saying the alternative of "I really tried, but boy filesystems are hard and maybe the NFS mount disappeared, and well shucks, couldn't find it! 404!".

We should interpret the RFC as written which is that this particular server could not find the resource. That does not mean the resource is not findable by this server at a different path or by a different server at a different host.

I really do not understand your argument.

There is no defined equivalency between host1/one/path and host2/other/path, even if the resources returned could potentially be the same.

There is no retry formula for a 404 at one URL that might return 200 at another URL.

There is no defined meaning for the same resource at another location. HTTP 404 makes no attempt to comment on the uniqueness or commonness of a resource. No comment on whether that resource existed in the past, is expected to exist later, or in whose imagination it could conceivably exist in the future.

The HTTP response simply states whether the resource was found to exist at the specified location at the time of request. Any further conclusions drawn from a 404 are speculative.

What does "get processed" mean? Plenty of web server frameworks allow generic handlers or middle ware that can handle any path passed to them.

That's a succinct definition, happy to admit that's a better argument than mine

It's the difference between "There is nothing handling this route at all" and "there is something handling this route but the object isn't found." To me the former is an HTTP 404 and the latter is an application "Not Found."

But I also very much don't like playing the "if you expose your app over HTTP you should assimilate HTTP semantics and do a fuzzy lossy map of your application to HTTP verbs and HTTP status codes." I leave the HTTP semantics to the front end web server and live on top.

> It's the difference between "There is nothing handling this route at all" and "there is something handling this route but the object isn't found."

'Nothing handling this route' has no meaning, because routes have no meaning in a hypertext application. Clients should not generally be constructing URLs by hand; they should be receiving them from the servers they communicate with.

In the example in the article, an application dealing with employees should not be constructing URLs by appending employee IDs to strings; rather, every reference to an employee in the application should be to a URL rather than an ID. So when it requests a list of employees, it receives the equivalent of {/api/v1/employees/1, /api/v1/employees/2 … /api/v1/employees/N} rather than {1, 2 … N}.

> I also very much don't like playing the "if you expose your app over HTTP you should assimilate HTTP semantics and do a fuzzy lossy map of your application to HTTP verbs and HTTP status codes."

If you are building a hypertext application, then you should build a hypertext application. It's completely possible. Off the top of my head, protocols such as ACME (used by Let's Encrypt) are good examples to follow.

Yep, there's absolutely no reason an application ought to be guessing URLs, and therefore no reason it should ever be requesting /api/v1/employees/69 where employee 69 doesn't exist. If it does, it's playing silly buggers exactly as much as if it were to request /api/v69/nice/. Any user resources it needs to access will have had URLs provided to the application by another page.

Example Code:

   users = http.client.get("https://yourapi.com/users")

   # Frobulate each user
   for user in users:
      user = http.client.post(user.frobulate_url)
      # While this is running somewhere on the other side of 
      # the world someone deletes one of the users. Oops.

Assuming, users (i.e developers) will just never mistype a URL so you don't have to give useful feedback is just like being a bad netzen.

That's a fair example. And returning 404 (Not Found) or 410 (Gone) is the most useful kind of feedback. More explanation in the body of the 404 response is helpful too, of course.

> Clients should not generally be constructing URLs by hand

I'm not sure I get this, every API doc is like "go to /users for the users and here's the methods we support, the payloads, and responses" If someone mistypes it and tried to get "/user" I want to send a 404 to be like "there is nothing here."

> In the example in the article, an application dealing with employees.

This is all very nice when your domain maps nicely to objects. My litmus tests for this is what would the semantics of mysql.net/query?db=mydb,q='select * from table;' look like.

* If the result is an empty record set should it return 404? Ew. I think it should be 200 with the response being `[]`.

* If you're not allowed to access a table should you get 403?

"Select *" is like find/ search - any API that could logically match multiple entities and return a list should stick to 200 in the case of an empty set. But for an API designed to return just the specific single resource requested there's a decent case for a 4xx status code if it doesn't exist (400/404/410/422 all being justifiable depending on your preferences).

Your example is just a filtered index, you would receive a 200 with no results just like any other index route with a filter applied.

Isn't that enough that there are originalists for constitution, do we now have to have "what did the founding fathers^H^H^H^H^H creators of HTTP mean"-people? That was 30 years ago. Web has evolved since then. What was a good solution then may not be one now. How people work with HTTP now and then is completely different.

I'll take "People who really need to understand the principle of of Chesterton's fence" for $200, Alex...

Or, people who should be designing a protocol specific to their application, rather than abusing HTTP. Really, it's okay! You don't actually have to use HTTP for everything!

The most recent specification of HTTP semantics is about a month old.