I appreciate the kind words, thank you.

I've said it in other responses, but maybe I should have been specific that I was referring to HTTP RPC (explicitly not citing REST for a reason).

Perhaps a combination of both is best, but in my experience a nice clean break between these 2 layers at the protocol level helps clients simplify their handling of responses.

2xx: Go ahead and parse (another commenter pointed out Content-Type. That one always gets me)

4xx/5xx: Something bad happened and the request wasn't processed by the server, either because it blew up (5xx) or because you did something _very_ wrong (4xx)

The objective is clarity to the caller.

It's a little obtuse but I think it works well with that objective in mind.

If it's not REST then shouldn't the url be /api/v1/employees?id=1000 instead of encoding the employee id in the URL? In this case the path is the endpoint, so a employee id is a parameter and not a controller action.

> If it’s not REST then shouldn’t the url be /api/v1/employees?id=1000 instead of encoding the employee id in the URL?

The query portion of a URL is, in fact, part of the URL, so that is encoding the employee id in the URL, and REST doesn’t care about how URLs are constructed, in the first place (in fact, excessive concerns about out-of-band knowledge about how URLs are constructed mostly are a sign of not doing HATEOAS, in contravention of the REST architectural style.)

Yes I used the wrong word. I meant "instead of encoding the employee id in the path?"

And instead of "if its not rest" I meant (in the context of the article) "if it's HTTP RPC" because the author clarified that they were talking about RPC rather than REST.

Remote Procedure Calls typically identify "endpoints" such that a specification of the endpoints could be compiled into a host language's function-calls. The logical way to do that with HTTP is to have a path be the function, and HTTP parameters (whether url or posted) be the parameters of the function.

Using a URL that has both a resource ID encoded in the path and also query parameters is a mixture of REST and RPC. Since the example given in the article does not show parameters, I think it is reasonable to call it REST, as many other commenters here have inferred. The author claiming it is RPC doesn't jive with my expectations for RPC.

Maybe I'm just complaining about calling it RPC. If it's neither RPC nor REST then it's just some random mismash of HTTP-ish stuff, and I don't think that's a particularly strong argument for "things should be done like this".

I tend to split route params and query params by their function:

Query params tell me something _about_ how I want the data filtered, displayed, or grouped.

Route params _identify_ the object or collection I'm retrieving.

> Route params _identify_ the object

Well... in REST they do :-)

HTTP is designed to give access to a tree of files. The REST design says "lets fully embrace the idea that we are representing our data and program state as a virtual tree of files." You can embrace or reject that to various degrees, but the closer a design is to a virtual tree of files, the more "RESTful" I say it is.

In a RPC ("procedure call") paradigm, you have a collection of named procedures, each of which takes parameters/input and returns a result/output. Anything that isn't the procedure name is a parameter to the procedure. Some are mandatory parameters, and some are optional parameters, but in the most straightforward implementation of "HTTP RPC", the path indicates which procedure, and parameters to the procedure should be a HTTP parameters (or request body). Also note that in this case the HTTP status '404' would indicate the presence or absence of the RPC endpoint, like the author wanted, and the procedure would be expected to return 200 for a within-spec return value, or possibly 422 or 5xx to represent an application-level exception to be propagated to the caller.

There's nothing stopping us from mixing the paradigms, and in fact nobody is forcing anyone to use any paradigm at all, since we can literally do whatever we want with the HTTP path, uri, method, and headers. But when the original article claims to be doing RPC and not REST, I think that is just sowing confusion onto the topic.

I really enjoyed that SO thread, and your answer. In my opinion your take is correct, to the extent that it is fascinating that it is a controversial topic. The majority of people, (and by people, likely limited to software developers), seem to not fully understand HTTP status codes. This is of course fine, the fascinating part is the extent they insist they do. Whenever the majority, in any technically field, opine something different, I assume they are right, and I've missed something. But having designed APIs for years, I can safely say that it doesn't apply here.

Also, the OP article does explain well what could cause this misunderstanding. HTTP resource nouns shouldn't ever be "guessed". The resource either exist or it doesn't. And if it exists, it either has a data, or it doesn't.

404: it doesn't exist 204: it exists and has no data to parse.

Wow, 452 upvotes and 89 downvotes on your answer. Very controversial, indeed!

While I agree with you, I sometimes misuse 200 OK even for actual errors. Most times because whatever internal library I've used to do the requests have made it hard to parse the error data if it happens (just throws a general exception instead when it encounters a 4XX or 5XX). Or sometimes because the request failing is somewhat expected, but the client library then insists on doing lots of error handling when it fails (logging, alarms, circuit breakers and whatnot), polluting everything.

TIL: You can view upvote/downvote count by clicking on the score. I only needed 12 years on SO to find this out...

Only if you attained 1000 reputation. https://stackoverflow.com/help/privileges/established-user

I have like 25k points so I probably had this for a while now.

Looks like HN people are changing that as we speak

Reading this discussion on hn and stackoverflow, I feel sometimes software development is more philosophy than engineering.

Yes, software dev absolutely is closer to philosophy than engineering.

There is such a thing as software engineering, but that isn't what most of us do (nor is it what we should be doing, IMO).

NASA needs software engineers. Low-level critical systems need them, so the G-MAFIA has a few.

For most business purposes, though, the iterative exploratory "let's get a UI out there and see how it works" is exactly what we need.

It's a useful, cost-effective strategy when lives aren't on the line, and it isn't engineering.

(My current job title is "Software Alchemist")

Only if you let it. Developers tend to overthin things. Be careful on where you spend you energy on.

Because honestly the answer is, as long as you are consistent, it really doesn't matter if you use status codes or not.