Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Most RESTful APIs aren't really RESTful

florian-kraemer.net

Post reply on HN
Print view View original

531–540 of 580 posts

Re: Most RESTful APIs aren't really RESTful

#531

Post by actionfromafar »

agumonkey wrote: post #530
actionfromafar wrote: post #523

Earlier quoted context omitted.

If younger me had been told, "one day kid, you will miss working with XML", I'd have laughed. YAML made me miss JSON. JSON made me miss XML.

The pattern I observe is that in old industries, people who paid the cost, try to come up with a big heavy solution (xml, xsd, xpath), but newcomers will not understand the need, and bail onto simpler ideas (json), until they hit the wall and start to invent their own (jsonschema, jquery). same goes for java vs php/python

Definitely. And often, it's the right call, or the thing wouldn't generate any business value (such as money) at all in a reasonable time.

But boy, how messy spaghetti don't we get for it, sometimes.

(Invent their own, badly, at first. Sigh.)

Re: Most RESTful APIs aren't really RESTful

#532

Post by infecto »

curt15 wrote: post #364
infecto wrote: post #150

Earlier quoted context omitted.

So you enjoy being pedantic for the sake of being pedantic? I see no useful benefit either from a professional or social setting to act like this. I don’t find this method of discovery very productive and often regardless of meeting some standard in the API the real peculiarities are in the logic of the endpoints and not the surface.

What some people call pedantic, others may call precision. I normally just call the not-quite-REST API styles as simply "HTTP APIs" or even "RPC-style" APIs if they use POST to retrieve data or name their routes in terms of actions (like some AWS APIs).

Like all things in life it’s about balance. If you are to say things like the person I replied to says he does you are ultimately creating friction for absolutely no gain. Hence why I said being pedantic for the sake of being pedantic or in other words, being difficult for no good reason. There is a time and place for everything but over a decade plus of working and building many different APIs I see no benefit.

I cannot even recall a time where it caused me enough issues to even think about it later on. The business logic. I have had moments where I thought something was strange in a Elasticsearch API but again it was of no consequence.

Re: Most RESTful APIs aren't really RESTful

#533

Post by incrudible »

rafark wrote: post #408
motorest wrote: post #144

Earlier quoted context omitted.

> I sympathize with the pedantry here and found Fielding's paper to be interesting, but this is a lost battle. Why do people feel compelled to even consider it to be a battle? As I see it, the REST concept is useful, but the HATEOAS detail ends up having no practical value and creates more problems than the ones it solves. This is in line with the Richardson maturity model[1], where the apex of REST includes all the…

> Why do people feel compelled to even consider it to be a battle? Because words have specific meanings. There’s a specific expectation when using them. It’s like if someone said “I can’t install this app on my iPhone” but then they have an android phone. They are similar in that they’re both smartphones and overall behave and look similar, but they’re still different. If you are told an api is restful there’s an exp…

Words derive their meaning from the context in which they are (not) used, which is not fixed and often changes over time.

Few people actually use the word RESTful anymore, they talk about REST APIs, and what they mean is almost certainly very far from what Roy had in mind decades ago.

People generally do not refer to all smartphones as iPhones, but if they did, that would literally change the meaning of the word. Examples: Zipper, cellophane, escalator… all specific brands that became ordinary words.

Re: Most RESTful APIs aren't really RESTful

#534

Post by osigurdson »

lucfranken wrote: post #494
osigurdson wrote: post #264

Earlier quoted context omitted.

>> /things/:id/child/:child_id It seems that nesting isn't super common in my experience. Maybe two levels if completely composite but they tend to be fairly flat.

Generally only /companies/:companyId/buildings And then you get a list of all buildings for this company. Every building has a url like: /buildings/:buildingId So you constantly get back to the root. Only exception is generally a tenant id which goes upfront for all requests for security/scoping purposes.

This seems like a really good model. It keeps things flat and easy to extend.

Re: Most RESTful APIs aren't really RESTful

#535

Post by _heimdall »

nsonha wrote: post #207
_heimdall wrote: post #98

Earlier quoted context omitted.

You realize that anyone using a browser to view HTML is using HATEOS, right? You could probably argue whether SPAs fit the bill, but for sure any server rendered or static site is using HATEOS. The point isn't that clients must have absolutely no prior knowledge of the server, its that clients shouldn't have to have complete knowledge of the server. We've grown used to that approach because most of us have been build…

HATEOAS is anything that serves the talking point now apparently

What do you mean? Both HATEOAS and REST have clear definitions.

Re: Most RESTful APIs aren't really RESTful

#536

Post by _heimdall »

dwaltrip wrote: post #307
_heimdall wrote: post #98

Earlier quoted context omitted.

You realize that anyone using a browser to view HTML is using HATEOS, right? You could probably argue whether SPAs fit the bill, but for sure any server rendered or static site is using HATEOS. The point isn't that clients must have absolutely no prior knowledge of the server, its that clients shouldn't have to have complete knowledge of the server. We've grown used to that approach because most of us have been build…

Can you be more specific? What exactly is the partial knowledge? And how is that different from non-conforming APIs?

Not totally sure I understand your question, sorry if I don't quite answer it here.

With REST you need to know a few things like how to find and parse the initial content. I need a browser that can go from a URL to rendered HTML, for example. I don't need to know anything about what content is available beyond that though, the HTML defines what actions I can take and what other pages I can visit.

RPC APIs are the opposite. I still need to know how to find and parse the response, but I need to deeply understand how those APIs are structured and what I can do. I need to know schemas for the API responses, I need to know what other APIs are available, I need to know how those APIs relate and how to handle errors, etc.

Re: Most RESTful APIs aren't really RESTful

#537

Post by Joker_vD »

potamic wrote: post #487
Joker_vD wrote: post #470

Earlier quoted context omitted.

> - The team constantly bikesheds over correct status codes and at least a few are used contrary to the HTTP spec I really wish people just used 200 status code and put encoded errors in the payloads themselves instead of trying to fuse the transport layer's (which HTTP serves as, in this case) concerns with the application's concerns. Seriously, HTTP does not mandate that e.g. "HTTP/1.1 503 Ooops\r\n\r\n" should be…

The point of status codes is to have a standard that any client can understand. If you have a load balancer, the load balancer can unhealthy backends based on the status code. Similarly if you have some job scheduler or workflow engine that's calling your API, they can execute an appropriate retry strategy based on the status code. The client in most cases does not care about why something failed, only whether it has…

> The client in most cases does not care about why something failed, only whether it has failed.

"...and therefore using different status codes in the responses is mostly pointless. Therefore, use 200 and put "s":"error" in the response".

> Being able to tell apart if the failure was due to reverse proxy or database or whatever is the server's concern.

One of the very common failures is for the request to simply never reach "the server". In my experience, one of the very first steps in improving the error handling quality (on the client's side) is to start distinguishing between the low-level errors of "the user has literally no connection Internet" and "the user has connected somewhere, but that thing didn't really speak the server protocol", and the high-level errors "the client has talked with the application server (using the custom application protocol and everything), and there was an error on the application server's side". Using HTTP-status codes for both low- and high-level errors makes such distinctions harder to figure out.

Re: Most RESTful APIs aren't really RESTful

#538

Post by jerf »

cyberax wrote: post #418
jerf wrote: post #376

Earlier quoted context omitted.

I'd agree with your great-grandparent post... people get stuff done because of that. There has been no lack of heavyweight, pre-declare everything, code-generating, highly structured, prescriptive standards that sloppyREST has casually dispatched (pun fully intended) in the real world. After some 30+ years of highly prescriptive RPC mechanisms, at some point it becomes time to stop waiting for those things to unseat…

> There has been no lack of heavyweight, pre-declare everything, code-generating, highly structured, prescriptive standards Care to list them? REST mania started around early 2000-s, and at that time there was only CORBA available as a cross-language portable RPC. Microsoft had DCOM. And that was it. There was almost nothing else. It was so bad that ZeroC priced their ICE suite based on a PERCENTAGE OF GROSS SALES: h…

I don't just mean the ones that existed at the time of the start of REST. I mean all the ones that have come up since then as well and failed to displace it.

Arguably the closest thing to a prescriptive winner is laying OpenAPI on top of REST APIs.

Also, REST defined as "A vaguely HTTP-ish API that carries JSON" would have to be put later than that. Bear in mind that even after JSON was officially "defined" it's not like it instantly spread everywhere. I am among the many people that reconstructed something like it because we didn't know about it yet, even though it was nominally years old by that point. It took years to propagate out. I'd put "REST as we are talking about it" as late 200xs at the earliest for when it was really popular and only into the 2010s as to when you started expecting people to mean that when they said "Web API".

Re: Most RESTful APIs aren't really RESTful

#539

Post by bunderbunder »

agumonkey wrote: post #386
PaulHoule wrote: post #325

Earlier quoted context omitted.

Fielding won the war precisely because he was intellectually incoherent and mostly wrong. It's the "worse is better" of the 21st century. RPC systems were notoriously unergonomic and at best marginally successful. See Sun RPC, RMI, DCOM, CORBA, XML-RPC, SOAP, Protocol Buffers, etc. People say it is not RPC but all the time we write some function in Javascript like const getItem = async (itemId) => { ... } which does…

When I realized that I was calling openapi-generator to create client side call stubs on non-small service oriented project, I started missing J2EE EJB. And it takes a lot to miss EJB. I'd like to ask seasoned devs and engineers here. Is it the normal industry-wide blind spot where people still crave for and are happy creating 12 different description of the same things across remote, client, unit tests, e2e tests, o…

I keep pining for a stripped-down gRPC. I like the *.proto file format, and at least in principle I like the idea of using code-generation that follows a well-defined spec to build the client library. And I like making the API responsible for defining its own error codes instead of trying to reuse and overload the transport protocol's error codes and semantics. And I like eliminating the guesswork and analysis paralysis around whether parameters belong in the URL, in query parameters, or in some sort of blob payload. And I like having a well-defined spec for querying an API for its endpoints and message formats. And I like the well-defined forward and backward compatibility rules. And I like the explicit support for reusing common, standardized message formats across different specs.

But I don't like the micromanagement of field encoding formats, and I don't like the HTTP3 streaming stuff that makes it impossible to directly consume gRPC APIs from JavaScript running in the browser, and I don't like the code generators that produce unidiomatic client libraries that follow Google's awkward and idiosyncratic coding standards. It's not that I don't see their value, per se*. It's more that these kinds of features create major barriers to entry for both users and implementers. And they are there to solve problems that, as the continuing predominance of ad-hoc JSON slinging demonstrates, the vast majority of people just don't have.

Re: Most RESTful APIs aren't really RESTful

#540

Post by lucideer »

tgv wrote: post #159
lucideer wrote: post #129

Earlier quoted context omitted.

> - CRUD actions are mapped to POST/GET/PUT/DELETE Agree on your other three but I've seen far too many "REST APIs" with update, delete & even sometimes read operations behind a POST. "SOAP-style REST" I like to call it.

Do you care? From my point of view, post, put, delete, update, and patch all do the same. I would argue that if there is a difference, making the distinction in the url instead of the request method makes it easier to search code and log. And what's the correct verb anyway? So that's an argument that there may be too many request methods, but you could also argue there aren't enough. But then standardization becomes…

> Do you care?

I don't. I could deliver a diatribe on how even the common arguments for differentiating GET & POST don't hold water. HEAD is the only verb with any mild use in the base spec.

On the other hand:

> correct status codes and at least a few are used contrary to the HTTP spec

This is a bigger problem than verb choice & something I very much care about.

Post reply on HN