6 ms·

Here's how you do it: - REST/Hypermedia when you're actually building a website (not app) and your "site" is a state machine - OpenAPI when you expose and API

Here's how you do it: - REST/Hypermedia when you're actually building a website (not app) and your "site" is a state machine - OpenAPI when you expose and API to 3rd parties - Isomorphic TypeScript APIs when you're using TS on both backend and frontend [0] - GraphQL when the frontend needs to talk to an API layer provided by different teams - OpenAPI when one backend talks to another backend - gRPC might be an option, but most teams don't need it [0]: https://wundergraph.com/blog/isomorphic_typescript_apis_end_to_end_type_safety_between_client_and_server https://wundergraph.com/blog/isomorphic_typescript_apis_end_...

deleted 4y ago
[deleted]
flashgordon 4y ago
One thing Id suggest - "gRPC might be an option but most teams dont need it" - needs a revisit. As a backend-dev (who does front end when needed - and that too by slapping NextJS on an API) I have found starting from a grpc set of services and generating http/openapi specs from it to be much for maintainable and understandable than starting with the OpenAPI spec and working "inwards". Apart from a (mostly) single source of truth for my interface intent - I also get a system that is amenable to scalability concerns than most of the time when I started working inwards. I might be in the minority as most folks who build services come from a product background?
- jensneuse 4y ago
  If we compare gRPC to OpenAPI, we get the following. gRPC will be faster at the tradeoff of complexity. You need more tooling, you cannot easily inspect binary traffic, you cannot simply call gRPC from the web, you need a grpc web proxy, proxies and API gateways are more complex for gRPC than for an OpenAPI/REST-ish API, and the list goes on. I can put my protobuf in a registry, but the same applies to OpenAPI. So what really is the difference? And do we really need the gRPC level of performance with this hefty price of complexity? I doubt it. Most of the time, your database will be much slower than what gRPC might give you in performance compared to OpenAPI. Sorry if I'm pushing back on this. It's not against you. I've just seen way too many devs and teams who created gRPC "micro" services and all they needed was one boring well designed OpenAPI monolith with good architecture. gRPC is great if you really really have the problems it tries to solve. I believe most companies have a much bigger problem than performance, the inability to design APIs. You cannot solve bad API design by using a faster tool. Fix your API design, OpenAPI is great.
  - flashgordon 4y ago
    Pushback is always good. I am not buying the argument (from having done large scale systems in both) that OpenAPI is significantly more productive than grpc - especially when building SaaS/control plane services. I do agree tooling is "prettier" for OpenAPI but that is artifact of needing that level of tooling for a spec that to me never felt as expressive to begin with (have to be careful not to get into Yaml vs syntax wars her). On the contrary reading/modifying/consuming grpc specs have never needed a custom UI. OpenAPI is way too tied in the hip with http (doesnt need to be) and a lot of things evolved that way. Grpc never had this problem. As you may have pointed out it needs an extra grpc-gateway plugin to generate a http gateway (which I actually is neat) +1 on the terrible state of grpc cli tooling (unless you are already working at a faang). -1 on Web proxy - As mentioned before I actually find that seperating a http "transaltion" gateway from your core biz logic is a win in my mind. +1 On way too many microservices. IMO whether you use GRPC or OA, you can build monoliths or way too many microservices. I have not felt GRPC explicitly enforced that. What I did get from grpc is the logical seperation with grpc (you can still bundle multiple services in a single binary vs as seperate microservices) if you want. With grpc (nay proto spec) building a service becomes a logical exercise over how do i structure URLs vs what verbs to use etc. PS: On a completely diff note I actually like your approach to isomorphic types. My switching to the grpc side was largely motivated by this single source of truth from whence all layer specific types came forth from!
  - random3 4y ago
    Here's a bunch of random points (this deserves a full blog post) - it's not about performance - OpenAPI needs and has tooling (it just doesn't work) - think about documentation, client/server code and evolution support for forward/backward compatibility, type safety, etc. - you can build monoliths and microservices with both - gRPC / protobuf gives you a pragmatic separation of concerns (and typing among other things) - gRPC allows exposing REST/OpenAPI with defualt tooling and it works - there's an extensive set of best practices that combine the best of both worlds - just read https://google.aip.dev/ https://google.aip.dev/ - if the workd prefers GraphQL, you're out of luck - gRPC / protobuf help you focus on the actual contract and make everything else (that's 90% of time) a non-problem. --- Disclaimer: I'm in the grpc (and protobuf) camp and have built APIs with REST, Thrift and gRPC/Protobuf for more than 15 years (gRPC mostly last 5 years) As an infrastructure startup we have to both expose and consume both REST and gRPC. If you build APIs and decide to handle the above manually - you must feel productive doing work that compilers and code automation tools have been invented for. However tooling should automate it for you.
lazyasciiart 4y ago
Why does OpenAPI appear to be an alternative to REST in your list?
- jensneuse 4y ago
  I understand REST APIs more like Hypermedia APIs, where you go to the landing page, it contains links, you follow them, you leverage content types, etc... So by definition, a REST API has no specification, it's an API that the agent can explore. In contrast, an OpenAPI is a REST-ish API with an OpenAPI specification. It's not as dynamic as REST, it's not Hypermedia, it's much more "JSON over HTTP" but also not exactly RPC.
  - shagie 4y ago
    Building on this... Look at https://api.github.com/users/octocat https://api.github.com/users/octocat Or the OpenID Connect and /.well-known/openid-configuration https://openid.net/specs/openid-connect-discovery-1_0.html https://openid.net/specs/openid-connect-discovery-1_0.html And while I might be invoking scotsmen, very few things look like https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc... and so are best described as "REST like" or "RESTish".
  - nonethewiser 4y ago
    But REST is the REST specification. REST doesnt just mean HTTP
timr 4y ago
Simplify that to: - REST by default - everything else might be an option, but you need to justify it with specific reasons. Also, having a JS-driven front end or multiple teams is not an automatic justification for the complexity of GraphQL. GraphQL is a huge burden, for very little practical gain. Most companies have very small number of examples of conflict areas where queries need to be optimized, and for the most part, these can be resolved through smarter front-end engineering (like not throwing React at CRUD websites). It's amazing how we managed to build large-scale websites with essentially all modern functionality without all of this stuff for years and years, and only since 2012 or so have these tools become "necessary" (and I'm being generous with 2012...it's more recent than that).
- jensneuse 4y ago
  I more or less agree, but recent advances in tooling has changed this. E.g we've built a GraphQL to JSON RPC compiler [0], so we're hiding GraphQL behind a JSON RPC wall which also enables powerful code generation. We're using this successfully to build our own cloud [1] using our own tooling and I quite like it. Shameless plug, I'd love to get feedback if you have the time to try it out. [0]: https://docs.wundergraph.com/docs/features/graphql-to-json-rpc-compiler https://docs.wundergraph.com/docs/features/graphql-to-json-r... [1]: https://cloud.wundergraph.com https://cloud.wundergraph.com
  - timr 4y ago
    I mean...ok, but...wow. You built a compiler?? For writing a web app? And you're not Facebook? Look, maybe this is totally appropriate for your application domain. I don't know. But this kind of "power" is immensely complex. We have to be honest about the costs. I have to keep reminding people that essentially all functionality of the modern web existed prior to 2012.
    - deleted 4y ago
      [deleted]
    - satvikpendem 4y ago
meowtimemania 4y ago
The huge thing I love with graphql (and this probably works with OpenAPI as well) is run time mock generation. It makes writing tests a breeze and semi enjoyable. example: https://www.freecodecamp.org/news/a-new-approach-to-mocking-graphql-data-1ef49de3d491/ https://www.freecodecamp.org/news/a-new-approach-to-mocking-...
senda 4y ago
Should graphql ever be used to just cover all the basis of system integration?

deleted 4y ago

[deleted]

flashgordon 4y ago

One thing Id suggest - "gRPC might be an option but most teams dont need it" - needs a revisit. As a backend-dev (who does front end when needed - and that too by slapping NextJS on an API) I have found starting from a grpc set of services and generating http/openapi specs from it to be much for maintainable and understandable than starting with the OpenAPI spec and working "inwards". Apart from a (mostly) single source of truth for my interface intent - I also get a system that is amenable to scalability concerns than most of the time when I started working inwards. I might be in the minority as most folks who build services come from a product background?

jensneuse 4y ago
If we compare gRPC to OpenAPI, we get the following. gRPC will be faster at the tradeoff of complexity. You need more tooling, you cannot easily inspect binary traffic, you cannot simply call gRPC from the web, you need a grpc web proxy, proxies and API gateways are more complex for gRPC than for an OpenAPI/REST-ish API, and the list goes on. I can put my protobuf in a registry, but the same applies to OpenAPI. So what really is the difference? And do we really need the gRPC level of performance with this hefty price of complexity? I doubt it. Most of the time, your database will be much slower than what gRPC might give you in performance compared to OpenAPI. Sorry if I'm pushing back on this. It's not against you. I've just seen way too many devs and teams who created gRPC "micro" services and all they needed was one boring well designed OpenAPI monolith with good architecture. gRPC is great if you really really have the problems it tries to solve. I believe most companies have a much bigger problem than performance, the inability to design APIs. You cannot solve bad API design by using a faster tool. Fix your API design, OpenAPI is great.
- flashgordon 4y ago
  Pushback is always good. I am not buying the argument (from having done large scale systems in both) that OpenAPI is significantly more productive than grpc - especially when building SaaS/control plane services. I do agree tooling is "prettier" for OpenAPI but that is artifact of needing that level of tooling for a spec that to me never felt as expressive to begin with (have to be careful not to get into Yaml vs syntax wars her). On the contrary reading/modifying/consuming grpc specs have never needed a custom UI. OpenAPI is way too tied in the hip with http (doesnt need to be) and a lot of things evolved that way. Grpc never had this problem. As you may have pointed out it needs an extra grpc-gateway plugin to generate a http gateway (which I actually is neat) +1 on the terrible state of grpc cli tooling (unless you are already working at a faang). -1 on Web proxy - As mentioned before I actually find that seperating a http "transaltion" gateway from your core biz logic is a win in my mind. +1 On way too many microservices. IMO whether you use GRPC or OA, you can build monoliths or way too many microservices. I have not felt GRPC explicitly enforced that. What I did get from grpc is the logical seperation with grpc (you can still bundle multiple services in a single binary vs as seperate microservices) if you want. With grpc (nay proto spec) building a service becomes a logical exercise over how do i structure URLs vs what verbs to use etc. PS: On a completely diff note I actually like your approach to isomorphic types. My switching to the grpc side was largely motivated by this single source of truth from whence all layer specific types came forth from!
- random3 4y ago
  Here's a bunch of random points (this deserves a full blog post) - it's not about performance - OpenAPI needs and has tooling (it just doesn't work) - think about documentation, client/server code and evolution support for forward/backward compatibility, type safety, etc. - you can build monoliths and microservices with both - gRPC / protobuf gives you a pragmatic separation of concerns (and typing among other things) - gRPC allows exposing REST/OpenAPI with defualt tooling and it works - there's an extensive set of best practices that combine the best of both worlds - just read https://google.aip.dev/ https://google.aip.dev/ - if the workd prefers GraphQL, you're out of luck - gRPC / protobuf help you focus on the actual contract and make everything else (that's 90% of time) a non-problem. --- Disclaimer: I'm in the grpc (and protobuf) camp and have built APIs with REST, Thrift and gRPC/Protobuf for more than 15 years (gRPC mostly last 5 years) As an infrastructure startup we have to both expose and consume both REST and gRPC. If you build APIs and decide to handle the above manually - you must feel productive doing work that compilers and code automation tools have been invented for. However tooling should automate it for you.

lazyasciiart 4y ago

Why does OpenAPI appear to be an alternative to REST in your list?

jensneuse 4y ago
I understand REST APIs more like Hypermedia APIs, where you go to the landing page, it contains links, you follow them, you leverage content types, etc... So by definition, a REST API has no specification, it's an API that the agent can explore. In contrast, an OpenAPI is a REST-ish API with an OpenAPI specification. It's not as dynamic as REST, it's not Hypermedia, it's much more "JSON over HTTP" but also not exactly RPC.
- shagie 4y ago
  Building on this... Look at https://api.github.com/users/octocat https://api.github.com/users/octocat Or the OpenID Connect and /.well-known/openid-configuration https://openid.net/specs/openid-connect-discovery-1_0.html https://openid.net/specs/openid-connect-discovery-1_0.html And while I might be invoking scotsmen, very few things look like https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc... and so are best described as "REST like" or "RESTish".
- nonethewiser 4y ago
  But REST is the REST specification. REST doesnt just mean HTTP

timr 4y ago

Simplify that to: - REST by default - everything else might be an option, but you need to justify it with specific reasons. Also, having a JS-driven front end or multiple teams is not an automatic justification for the complexity of GraphQL. GraphQL is a huge burden, for very little practical gain. Most companies have very small number of examples of conflict areas where queries need to be optimized, and for the most part, these can be resolved through smarter front-end engineering (like not throwing React at CRUD websites). It's amazing how we managed to build large-scale websites with essentially all modern functionality without all of this stuff for years and years, and only since 2012 or so have these tools become "necessary" (and I'm being generous with 2012...it's more recent than that).

jensneuse 4y ago
I more or less agree, but recent advances in tooling has changed this. E.g we've built a GraphQL to JSON RPC compiler [0], so we're hiding GraphQL behind a JSON RPC wall which also enables powerful code generation. We're using this successfully to build our own cloud [1] using our own tooling and I quite like it. Shameless plug, I'd love to get feedback if you have the time to try it out. [0]: https://docs.wundergraph.com/docs/features/graphql-to-json-rpc-compiler https://docs.wundergraph.com/docs/features/graphql-to-json-r... [1]: https://cloud.wundergraph.com https://cloud.wundergraph.com
- timr 4y ago
  I mean...ok, but...wow. You built a compiler?? For writing a web app? And you're not Facebook? Look, maybe this is totally appropriate for your application domain. I don't know. But this kind of "power" is immensely complex. We have to be honest about the costs. I have to keep reminding people that essentially all functionality of the modern web existed prior to 2012.
  - deleted 4y ago
    [deleted]
  - satvikpendem 4y ago

meowtimemania 4y ago

The huge thing I love with graphql (and this probably works with OpenAPI as well) is run time mock generation. It makes writing tests a breeze and semi enjoyable. example: https://www.freecodecamp.org/news/a-new-approach-to-mocking-graphql-data-1ef49de3d491/ https://www.freecodecamp.org/news/a-new-approach-to-mocking-...

senda 4y ago

Should graphql ever be used to just cover all the basis of system integration?