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

Understanding gRPC, OpenAPI and REST and when to use them in API design (2020)

cloud.google.com

Post reply on HN
Print view View original

61–70 of 286 posts

Re: Understanding gRPC, OpenAPI and REST and when to use them in API design (2020)

#61

Post by mjr00 »

nsonha wrote: post #48
lmm wrote: post #29

Earlier quoted context omitted.

> You can’t just give someone a simple command to call an endpoint—it requires additional tooling that isn’t standardized. GRPC is a standard in all the ways that matter. It (or Thrift) is a breath of fresh air compared to doing it all by hand - write down your data types and function signatures, get something that you can actually call like a function (clearly separated from an actual function function - as it shoul…

> GraphQL is even better just a casual sentence at the end? How about no. It's in the name, a query-oriented API, useless if you don't need flexible queries. Why don't you address the problem they talked about, what is the cli tool I can use to test grpc, what about gui client?

For GUI, I've been very happy with grpcui-web[0]. It really highlights the strengths of GRPC: you get a full list of available operations (either from the server directly if it exposes metadata, or by pointing to the .proto file if not), since everything is strongly typed you get client-side field validation and custom controls e.g. a date picker for timestamp types or drop-down for enums. The experience is a lot better than copy & pasting from docs for trying out JSON-HTTP APIs.

In general though I agree devex for gRPC is poor. I primarily work with the Python and Go APIs and they can be very frustrating. Basic operations like "turn pbtypes.Timestamp into a Python datetime or Go time.Time" are poorly documented and not obvious. proto3 removing `optional` was a flub and then adding it back was an even bigger flub; I have a bunch of protos which rely on the `google.protobuf.Int64Value` wrapper types which can never be changed (without a massive migration which I'm not doing). And even figuring out how to build the stuff consistently is a challenge! I had to build out a centralized protobuf build server that could use consistent versions of protoc plus the appropriate proto-gen plugins. I think buf.build basically does this now but they didn't exist then.

[0] https://github.com/fullstorydev/grpcui

Re: Understanding gRPC, OpenAPI and REST and when to use them in API design (2020)

#63

Post by voiceofunreason »

cyberax wrote: post #20

REST is just pure bullshit. Avoid it like a plague. It's a fundamentally flawed model, as it smears the call details across multiple different layers: 1. The URL that contains path and parameters 2. The HTTP headers 3. The request body that can come in multiple shapes and forms (is it a JSON or is it a form?) As a result, OpenAPI descriptions end up looking horrifying, in the best traditions of the early EJB XML desc…

"REST is just pure bullshit. Avoid it like a plague."

No it isn't. Evidence: I'm reading this in a web browser.

"...REST is intended for long-lived network-based applications that span multiple organizations. If you don’t see a need for the constraints, then don’t use them."

Bikeshedding the spelling of resource identifiers? Or what "verb" should be used to express specialized domain semantics? Yeah, _that_ is certainly plague bullshit.

Re: Understanding gRPC, OpenAPI and REST and when to use them in API design (2020)

#64

Post by hamandcheese »

lordofgibbons wrote: post #33
bitzun wrote: post #30

Unless you are doing bidirectional streaming (for which it seems pretty well suited, but I haven't used it, so it might be a fucking mess), grpc is usually a waste of time. Runtime transitive dependency hell, toolchain hell, and the teams inside Google that manage various implementations philosophically disagree on how basic features should work. Try exposing a grpc api to a team that doesn't use your language (parti…

I've used grpc at multiple companies and teams within these companies, all of them 100-500ish engineering team size, and never had these dependency and tool chain issues. It was smooth sailing with grpc.

I have worked full time at now two companies of that size making the dependency and tool chain problems not be a problem for all the normies.

Re: Understanding gRPC, OpenAPI and REST and when to use them in API design (2020)

#65

Post by curt15 »

Octoth0rpe wrote: post #16

Oof, I strongly disagree with this article's description of how REST apis are used, and the distinction between openAPI and rest. If I design a REST api in 2023, and in 2024 produce an openapi yaml or json file for that API with no other changes, is it somehow no longer a REST api? of course not. The article seems to be predicated on this distinction. > The least-commonly used API model is REST Is that true? I don't…

HATEOAS is crucial to what [Roy Fielding](https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...) calls REST APIs.

>A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations.

Most APIs that people call "RESTful" -- regardless of whether they come with an OpenAPI spec -- don't obey HATEOAS. A typical OpenAPI spec describes the possible request paths and verbs. However, you probably wouldn't be able to discover all that information just by starting from the entry point and parsing the `hrefs` in the response bodies.

Re: Understanding gRPC, OpenAPI and REST and when to use them in API design (2020)

#66

Post by jahewson »

gghoop wrote: post #31

I dislike the use of gRPC within the data center. People reach for it citing performance, but gRPC is not high performance and the quality of the available open source clients is very poor, particularly outside of the core C++/Java implementations like the nodejs implementation. I am not against the use of protobuf as an API spec but it should be possible to use it with a framing protocol over TCP, there just isn't a…

I agree, though Zod greatly helps with the JS schema issue. I’m keeping an eye on Microsoft’s TypeSpec project too: typespec.io for interoperable schema generation.

Re: Understanding gRPC, OpenAPI and REST and when to use them in API design (2020)

#67

Post by hamandcheese »

sitzkrieg wrote: post #25
rednafi wrote: post #13

Google somehow psyoped the entire industry to use gRPC for internal service communications. The devex of gRPC is considerably worse than REST. You can’t just give someone a simple command to call an endpoint—it requires additional tooling that isn’t standardized. Plus, the generated client-side code is some of the ugliest gunk you’ll find in any language.

i agree, was forced to use it at several companies and it was 99% not needed tech debt investment garbage even in go its a pain in the ass to have to regen and figure out versioning shared protos and it only gets worse w each additional language but every startup thinks they need 100 microservices and grpc so whatever

> even in go its a pain in the ass to have to regen and figure out versioning shared protos and it only gets worse w each additional language

The secret is: don't worry about it. There is no need to regenerate your proto bindings for every change to the protos defs. Only do it when you need to access something new in your application (which only happens when you will be making changes to the application anyway). Don't try and automate it. That is, assuming you don't make breaking changes to your protos (or if you do, you do so under a differently named proto).

Re: Understanding gRPC, OpenAPI and REST and when to use them in API design (2020)

#68

Post by eadmund »

Octoth0rpe wrote: post #16

Oof, I strongly disagree with this article's description of how REST apis are used, and the distinction between openAPI and rest. If I design a REST api in 2023, and in 2024 produce an openapi yaml or json file for that API with no other changes, is it somehow no longer a REST api? of course not. The article seems to be predicated on this distinction. > The least-commonly used API model is REST Is that true? I don't…

> > A signature characteristic of [REST APIs] is that clients do not construct URLs from other information

> I don't think this is true in practice.

'recursivedoubts: https://news.ycombinator.com/item?id=42799917

The blogger is completely correct. In a true REST (i.e., not JSON-RPC) API, the client has a single entry URL, then calls the appropriate HTTP verb on it, then parses the response, and proceeds to follow URLs; it does not produce its own URLs. Hypertext as the engine of application state.

For example, there might be a URL http://foocorp.example/. My OrderMaker client might GET http://foo.example/, Accepting type application/offerings. It gets back a 200 response of type application/offerings listing all the widgets FooCorp offers. The offerings document might include a URL with an order-creation relationship. That URL could be http://foocorp.example/orders, or it could be http://foocorp.example/82347327462, or it could be https://barcorp.example/cats/dog-attack/boston-dysentery — it seriously doesn’t matter.

My client could POST to that URL and then get back a 401 Unauthorized response with a WWW-Authenticate header with the value ‘SuperAuthMechanism system="baz"’, and then my client could prompt me for the right credentials and retry the POST with an Authorization header with the value ‘SuperAuthMechanism opensesame’ and receive a 201 response with a Location header containing a URL for the new empty order. That could be http://foocorp.example/orders/1234, or it could be https://grabthar.example/hammer — what matters is that my client knows how to interact with it using HTTP verbs, headers and content types, not what the URL’s characters.

Then my client might POST a resource with content type application/order-item describing a widget to that order URL, and get back 202 Accepted. Then it might POST another resource describing a gadget, and get back 202 Accepted. Then it might GET the original order URL, and get back a 200 OK of type application/order which shows the order in an unconfirmed state. That resource might include a particular confirm URL to PUT to, or perhaps my client might POST a resource with content type application/order-confirmation — all that would be up to the order protocol definition (along with particulars like 202, or 200, or 201, or whatever).

Eventually my client non-idempotently PUTs or POSTs or whatever, and from then on can poll the order URL and see it change as FooCorp fulfills it.

That’s a RESTful API. The World Wide Web itself is a RESTful API for dealing with documents and also complete multimedia applications lying about being documents, but the RESTful model can be applied to other things. You can even build a RESTful application using the same backend code in the example, but which talks HTML to human beings whose browsers ask for text/html instead of application/whatever. Or you might build a client which asks for ‘text/html; custom=orderML’ and knows how to parse the expected HTML to extract the right information, and everything shares common backend code.

Or you might use htmx and make all this reasonably easy and straightforward.

That’s what REST is. What REST is not, is GETting http://api.foocorp.example/v1/order/$ORDERID and getting back a JSON blob, then parsing out an item ID from the JSON blob, then GETting http://api.foocorp.example/v1/item/$ITEMID and so forth.

Re: Understanding gRPC, OpenAPI and REST and when to use them in API design (2020)

#69

Post by reactordev »

NAHWheatCracker wrote: post #45
lordofgibbons wrote: post #34

Earlier quoted context omitted.

That sounds more like a critique of the "senior" developer who didn't know grpc isn't compatible with browsers before adopting it than grpc itself.

Correct, I wasn't critiquing gRPC. I was critiquing a type of person who might push for gRPC. That developer probably thought of it as a novelty and made up reasons to use it. It was a big hassle that added to that teams workload with no upside.

When all you have is a hammer…

gRPC is fantastic for its use case. Contract first services with built in auth. I can make a call to a service using an API that’s statically typed due to code generation and I don’t have to write it. That said, it’s not for browsers so Mr gRPC dev probably had no experience in browser technologies.

A company I worked for about 10 years ago was heavy gRPC but only as a service bridge that would call the REST handler (if you came in over REST, it would just invoke this handler anyway). Everything was great and dtos (messages) were automatically generated! Downside was the serialization hit.

Re: Understanding gRPC, OpenAPI and REST and when to use them in API design (2020)

#70

Post by loudgas »

curt15 wrote: post #49
recursivedoubts wrote: post #28

> If your API is a REST API, then your clients never have to understand the format of your URLs and those formats are not part of the API specification given to clients. Roy Fielding, who coined the term REST: "A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any…

How does one even write an API client against a REST API that only publishes the initial entry point? in particular, how should the client discover the resources that can be manipulated by the API or the request/response models?

Your Web browser is probably the best example. When you visit a Web site, your browser discovers resources and understands how it can interact with them.
Post reply on HN