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

561–570 of 580 posts

Re: Most RESTful APIs aren't really RESTful

#561

Post by PaulHoule »

auszeph wrote: post #436
majkinetor wrote: post #327

Earlier quoted context omitted.

Amen. Particularly ISO8601.

ISO8601 is really broad with loads of edge cases and differing versions. RFC 3339 is closer, but still with a few quirks. Not sure why we can't have one of these that actually has just one way of representing each instant. Related: https://ijmacd.github.io/rfc3339-iso8601/

I love how that's live!

Since ISO 8601 costs 133 CHF I suspect hardly anybody has actually read it, I think if you wanted something that supports all the weird stuff you might find somebody wrote it in 390 assembly.

Re: Most RESTful APIs aren't really RESTful

#562

Post by bborud »

paulddraper wrote: post #435
cyberax wrote: post #360

Earlier quoted context omitted.

Just use gRPC or ConnectRPC (which is basically gRPC but over regular HTTP). It's simple and rigid. REST is just too "floppy", there are too many ways to do things. You can transfer data as a part of the path, as query parameters, as POST fields (in multiple encodings!), as multipart forms, as streaming data, etc.

The critical problem with gRPC is that it uses protocol buffers. Which are...terrible. Example: structured schema, but no way to require fields.

Some people complain about that, but I have yet to see anyone demonstrate that this is an actual problem. Show me the scenario where this is a show stopper.

You have all the permutations that sail under the name "REST" to some degree, where there seems to be no rules and everyone does something different. And then you have an RPC mechanism that is about two orders of magnitude tigher and people complain about not having required fields? How? Why? What are they on about?

I mean, if you write validation code for every type, by hand, you will probably still have to do less overall work than for REST'ish monstrosities. But since you have a lot more regularity, you can actually generate this code. Or use reflection.

How much time do people really spend on their interface types? After the initial design I rarely touch them. They're like less than a percent of the overall work.

Re: Most RESTful APIs aren't really RESTful

#563

Post by Joker_vD »

potamic wrote: post #547
Joker_vD wrote: post #537

Earlier quoted context omitted.

> 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 neve…

I did say most cases, not all cases. There are some concerns that are considered cross cutting, to have made it into the standard. For instance, many clients will handle a 401 by redirecting to an auth flow, or handle a 429 rate limited by backing off before making a request, handle 426 by upgrading the protocol etc. Not all statuses may be relevant for a given system, you can club several scenarios under a 400 or a…

> transport errors vs business errors

Yes, pretty much.

> But the important thing is all errors business or transport eventually need to map to a HTTP status code because that's the protocol you're ultimately speaking.

"But the important thing is, all errors, business or transport, eventually need to map to the set of TCP flags (SYN, ACK, FIN, RST, ...) because that's the protocol you're ultimately speaking". Yeah, they do map, technically speaking: to just an ACK. Because it's a payload, transported agnostically to its higher-level meaning. It's a yet another application of the end-to-end principle.

Re: Most RESTful APIs aren't really RESTful

#564

Post by cryptos »

The big problem I see with the practical adoption of REST principles is that a human can easily intpret a document and pick the desired transation (e.g. follow a link), but a program can not so easily do that. Maybe in the age of AI it becomes more realistic, but most of the time some "RESTful" back-end is used by a certain front-end application. What is needed is basically more like RPC. Maybe SOAP was closer to what we actually do and need. The specification and code generation was much better than what we have now with mediocre OpenAPI code generators.

Maybe gRPC or something like that will fill the gap ...

Re: Most RESTful APIs aren't really RESTful

#565

Post by SJC_Hacker »

motorest wrote: post #489
SJC_Hacker wrote: post #425

Earlier quoted context omitted.

JSON doesn’t really have data types beyond very simple ones

> JSON doesn’t really have data types beyond very simple ones What do you think primitive types are supposed to be?

I guess my point was something like an ISO 8601 date would be beyond the scope of a built in data type given JSONs philosophy of a minimal spec. It’s up to the end user to define types like that.

Re: Most RESTful APIs aren't really RESTful

#566

Post by jerf »

cyberax wrote: post #551
jerf wrote: post #538

Earlier quoted context omitted.

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…

> I mean all the ones that have come up since then as well and failed to displace it. They won inside large companies: Coral in Amazon, Protobufs/gRPC in Google, Thrift in Facebook, etc. And they are slowly spreading outside of them. OpenAPI is indeed an attempt to bring some order into the HTTP RPC world, and it's pretty successful. I'm pretty sure all the APIs that I used lately were based on OpenAPI descriptions.…

Yes, I agree with all of that stuff about using more structure in larger companies.

My meta point is that it is easy for programmers to come to the conclusion that all that should exist is the stuff that large companies use, as I see so many people believe, but if you try to model the world on that assumption you end up very frustrated and confused by how the real world actually works. You can't push a highly proscriptive, very detailed, high up-front work methology out on everyone. Not because it's a bad idea per se, or because it "wouldn't work", but because you literally can't. You can't force people to be "better" programmers than they are by pushing standards on them.

My gut leans in the direction of better specifications and more formal technologies, but I can't push that on my users. It really needs to be a pull operation.

Re: Most RESTful APIs aren't really RESTful

#567

Post by cyberax »

jerf wrote: post #566
cyberax wrote: post #551

Earlier quoted context omitted.

> I mean all the ones that have come up since then as well and failed to displace it. They won inside large companies: Coral in Amazon, Protobufs/gRPC in Google, Thrift in Facebook, etc. And they are slowly spreading outside of them. OpenAPI is indeed an attempt to bring some order into the HTTP RPC world, and it's pretty successful. I'm pretty sure all the APIs that I used lately were based on OpenAPI descriptions.…

Yes, I agree with all of that stuff about using more structure in larger companies. My meta point is that it is easy for programmers to come to the conclusion that all that should exist is the stuff that large companies use, as I see so many people believe, but if you try to model the world on that assumption you end up very frustrated and confused by how the real world actually works. You can't push a highly proscri…

> You can't force people to be "better" programmers than they are by pushing standards on them.

Oh, for sure. A company can just mandate something internally, whether it's a good idea or not. But superior approaches tend to slowly win out on merit even in the wider world. Often by standardizing existing practices, like OpenAPI did.

And I believe that strict prescriptive APIs with code generation are superior. This is also mirrored by the dynamic and static typing languages. I remember how dynamic languages were advertised in early 2000-s as more "productive" than highly prescriptive C++/Java.

But it turned out to be a mistake, so now even dynamic languages are gaining types.

Re: Most RESTful APIs aren't really RESTful

#568

Post by shadowgovt »

esafak wrote: post #451
ivan_gammel wrote: post #420

Earlier quoted context omitted.

That API doesn’t look like REST level 3 API. For example, there’s an endpoint to create a node. It is not referenced by root or anywhere else. GetNode endpoint does include some traversal links in response, but those links are part of domain model, not part of the protocol. HAL does offer a protocol by which you enhance your domain model with links with semantics and additional resources.

these levels? https://blog.restcase.com/4-maturity-levels-of-rest-api-desi...

It is interesting to me that GraphQL would be in "the swamp of POX," mostly because personal experience was that shifting from hand-built REST to GraphQL solved a lot of problems we had. Mostly around discovery and composition; the ability to sometimes ask for a little data and sometimes a lot at the same endpoint is huge, and the fact that all of that happens under the same syntax as opposed to smearing out such controls over headers, method, URI, and query params decreased cognitive load.

Perhaps the real issue was that XML is awful and a much thinner resource representation simplifies most of the problems for developers and users.

Re: Most RESTful APIs aren't really RESTful

#569

Post by bunderbunder »

PaulHoule wrote: post #558
bunderbunder wrote: post #539

Earlier quoted context omitted.

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 paraly…

I can write frickin' bash scripts that handle JSON APIs with curl, jq, here quotes and all that. A lot of people just do whatever comes to mind first and don't think about it so they don't get stuck with analysis paralysis. curl -fail Handling failure might be the real hardest programming problem ahead of naming and caches and such. It boggles my mind the hate people have for Exceptions which at least make you "try"…

I worked at a place that had a really great coding standard for working with exceptions:

1. Catch exceptions third-party code and talking to the outside world right away.

2. Never catch exceptions that we throw ourselves.

3. Only (and always) throw exceptions when you're in a state where you can't guarantee graceful recovery. Exceptions are for those exceptional circumstances where the best thing to do is fail fast and fail hard.

Re: Most RESTful APIs aren't really RESTful

#570

Post by crabmusket »

agumonkey wrote: post #511
crabmusket wrote: post #459

Earlier quoted context omitted.

I haven't written anything up - maybe one day - but our stack is `ts-morph` to get some basic metadata out of our "service definition" typescript files, `ts-json-schema-generator` to go from there to JSON Schema, `quicktype-core` to go to other languages. Schema validation and type generation vary by language. When we need to validate schemas in JS/TS land, we're using `ajv`. Our generation step exports the JSON Sche…

Can't thank you enough. I'm gonna try these and see.

One day I hope to publish this as a tool, or at least parts of it. But you know, that won't put food on the table.
Post reply on HN