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

141–150 of 286 posts

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

#141

Post by larusso »

I generally like the article. I wished the REST concept would have been explained with some code / payload examples though. Other the that it managed to steer me away from gRPG. All the cons he mentioned are huge deal breakers in my opinion. I would only consider if I can control both server and client and its implementation details (tech stack in this case).

But he addressed some issues with OpenAPI I constantly struggle with. And the fact that seemingly none is able to say what the standard is for certain patterns. And don’t get me started with OData …

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

#142

Post by XorNot »

physicles wrote: post #111
oppositelock wrote: post #98

I've been building API's for a long time, using gRPC, and HTTP/REST (we'll not go into CORBA or DCOM, because I'll cry). To that end, I've open sourced a Go library for generating your clients and servers from OpenAPI specs ( https://github.com/oapi-codegen/oapi-codegen ). I disagree with the way this article breaks down the options. There is no difference between OpenAPI and REST, it's a strange distinction. OpenAPI…

> There is no difference between OpenAPI and REST, it's a strange distinction. That threw me off too. What the article calls REST, I understand to be closer to HATEOAS. > I've open sourced a Go library for generating your clients and servers from OpenAPI specs As a maintainer of a couple pretty substantial APIs with internal and external clients, I'm really struggling to understand the workflow that starts with gener…

The oapi-codegen tool the OP was put out (which I use) solves this by emitting an interface though. OpenAPI has the concept of operation names (which also have a standard pattern), so your generated code is simply implementing operation names. You can happily rewrite the entire spec and provided operation names are the same, everything will still map correctly - which solves the coupling problem.

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

#143

Post by jitl »

mkleczek wrote: post #128
physicles wrote: post #111

Earlier quoted context omitted.

> There is no difference between OpenAPI and REST, it's a strange distinction. That threw me off too. What the article calls REST, I understand to be closer to HATEOAS. > I've open sourced a Go library for generating your clients and servers from OpenAPI specs As a maintainer of a couple pretty substantial APIs with internal and external clients, I'm really struggling to understand the workflow that starts with gener…

> This is why I created an abomination that uses go/ast and friends to generate the OpenAPI spec from the code. This is against "interface first" principle and couples clients of your API to its implementation. That might be OK if the only consumer of the API is your own application as in that case API is really just an internal implementation detail. But even then - once you have to support multiple versions of your…

OpenAPI spec being authored by a human or a machine, it can still be the same YAML at the end of the day, so why would one approach be more brittle / breaks your clients than the other?

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

#144

Post by nithril »

doctorpangloss wrote: post #126
azemetre wrote: post #110

Earlier quoted context omitted.

What would you recommend doing instead?

Do you need bidirectional streams? If so, you should write a bespoke protocol, on top of UDP, TCP or websockets. If you don't, use GraphQL.

"Write a protocol and GraphQL", god damn it escalates quickly.

Fortunately, there are intermediate steps.

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

#145

Post by jitl »

toprerules wrote: post #44

As someone who has worked at a few of the FAANGs, having thrift/grpc is a godsend for internal service routing, but a lot of the complexity is managed by teams building the libraries, creating the service discovery layers, doing the routing etc. But using an RPC protocol enables those things to happen on a much greater scale and speed than you could ever do with your typical JSON/REST service. I've also never seen a…

For a public API I wouldn’t do this, but for private APIs we just do POST /api/doThingy with a JSON body, easy peasy RPC anyone can participate in with the most basic HTTP client. Works great on every OS and in every browser, no fucking around with “what goes in the URL path” vs “what goes in query params” vs “what goes in the body”.

You can even do this with gRPC if you’re using Buf or Connect - one of the server thingies that try not to suck; they will accept JSON via HTTP happily.

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

#146

Post by rswail »

The problem with gRPC is the "R". It's been the same with JMI, Corba, ONC-RPC and all the others.

Making "procedure calls" remote and hiding them underneath client libraries means that programmers do not consider the inherent problems of a networked environment. Problems like service discovery, authentication, etc are hidden beneath something that "looks like" a local procedure call.

That's one problem, the other is that procedure calls are focusing on the verbs, not the nouns (called "entities" or "resources" in the article).

If you can't express an FSM about a noun and what causes its state to change, then how the hell do you know what it does or how changes to its environment affect it?

If you don't know whether some procedure call is idempotent, how the hell can you write code that handles the various network failure modes that you have to deal with?

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

#147

Post by thayne »

My experience with grpc was not good.

I was writing some python code to interface with etcd. At least at the time there wasn't a library compatible with etcd 3 that met my needs, and I only needed to call a couple of methods, so I figured I'd just use grpc directly, no big deal right?

So I copied the proto files from the etcd project to mine, then tried to figure out how to use protoc to generate python client code. The documentation was a little lackluster, especially on how to generate annotations for use with mypy or pyright, but whatever, it wasn't too hard to figure out the right incantation.

Except it didn't work. The etcd proto files had some annotations or includes or something that worked fine with the golang implementation, but didn't work with the Python implementation. I thought the proto files were supposed to be language agnostic. Well after a couple hours of trying to get the files working as is, I gave up and just modified the proto files. I deleted most of it, except for the types and methods I actually needed, got rid of some annotations, and I think I ended up needing to add some python specific annotations as well.

Then I finally got some python code, and a separate file for type annotations. But I still have issues. Eventually, I figured out that what was happening was that the package hierarchy of the proto files, and imports in those files has to match the python package names, and it uses absolute, rather than relative, imports. Ok, so surely there is an option to pass to protoc to add a prefix package to that, so I can use thes files under my own namespace right? Nope. Alright, I guess I have to update these protoc files again. It'll be a pain if I ever need to update these to match changes upstream.

Ok, now the code is finally working, let's make sure the types check. No. MyPy gives me errors. In the generated code. At first I assume I did something wrong, but after much investigation, I determine that protoc just generates type annotations that are not just wrong, but invalid. It annotates global variables as class variables, which MyPy, rightly, complains doesn't make sense.

To fix this I resort to some hackery that I saw another python project use to fix the import issue I mentioned earlier: I use sed to fix the pyi file. Is it hacky? Yes, but at this point, I don't care.

I assume that other people have had a better experience, given its popularity, but I can't say I would be happy to use it again.

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

#148

Post by rfw300 »

toprerules wrote: post #44

As someone who has worked at a few of the FAANGs, having thrift/grpc is a godsend for internal service routing, but a lot of the complexity is managed by teams building the libraries, creating the service discovery layers, doing the routing etc. But using an RPC protocol enables those things to happen on a much greater scale and speed than you could ever do with your typical JSON/REST service. I've also never seen a…

What do you mean by “leak verbs”?

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

#149

Post by thayne »

rswail wrote: post #146

The problem with gRPC is the "R". It's been the same with JMI, Corba, ONC-RPC and all the others. Making "procedure calls" remote and hiding them underneath client libraries means that programmers do not consider the inherent problems of a networked environment. Problems like service discovery, authentication, etc are hidden beneath something that "looks like" a local procedure call. That's one problem, the other is…

That is a problem, certainly, but not the only one.

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

#150

Post by jpc0 »

physicles wrote: post #111
oppositelock wrote: post #98

I've been building API's for a long time, using gRPC, and HTTP/REST (we'll not go into CORBA or DCOM, because I'll cry). To that end, I've open sourced a Go library for generating your clients and servers from OpenAPI specs ( https://github.com/oapi-codegen/oapi-codegen ). I disagree with the way this article breaks down the options. There is no difference between OpenAPI and REST, it's a strange distinction. OpenAPI…

> There is no difference between OpenAPI and REST, it's a strange distinction. That threw me off too. What the article calls REST, I understand to be closer to HATEOAS. > I've open sourced a Go library for generating your clients and servers from OpenAPI specs As a maintainer of a couple pretty substantial APIs with internal and external clients, I'm really struggling to understand the workflow that starts with gener…

> This is why I created an abomination that uses go/ast and friends to generate the OpenAPI spec from the code

OpenAPI is a spec not documentation. Write the spec first then generate the code from the spec.

You are doing it backwards, at least in my opinion.

Post reply on HN