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 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.
But the path does exist. The employee record represented by that path doesn't exist.
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.
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.
> 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.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.
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!".
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.
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.
'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.
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.
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?