Prototype GraphQL/Relay server & implementation

[jamesdphillips]

TODO

High Level

• [x] Try https://github.com/neelance/graphql-go Incomplete implementation; won't work with Relay without investment on our part.
• [x] Try https://github.com/graphql-go/graphql
• [x] Switch to found-relay for routing
• [x] Investigate alternatives to found-relay
• [x] Experiment w/ Relay vs. Redux & GraphQL

Practical elements that must be supported.

• [x] Build list that uses a connection
• [x] Build test interface
• [x] Build test union
• [x] Build test scalar types
• [x] Test Relay related extensions (global IDs, Relay mutations, connections, etc.)
• [x] Build a mutation that updates a resource
• [x] Build a mutation that creates a resource
• [x] Build a mutation that deletes a resource (ensure removed from connection.)
• [x] If we avoid Redux how do we handle authentication state?
• [ ] Experiment w/ client schema. Related issue.
• [ ] more..?

Issues

• [ ] graphql-go/relay doesn't not support creating connections w/ union types(?)
• [ ] ...?

[jamesdphillips]

Options

REST & Redux

Pros

• Most common solution.
• Redux generally liked in the community.
• Redux is very simple and it's approach makes it easy to debug application state.
• (At least in the short term) we can use APId.

Cons

• No guarantee that we don't implement our own API in future to match our web application's data requirements. (I suspect) similar to how Uchiwa's API aggregates and tweaks values.
• Redux friction:
  • From a purity v. practicality perspective: while very ideal it may be less practical.
  • My experience with Redux is, while it is very simple, for many developers it can be very difficult to pick up. Especially for if they are coming from a object-oriented background. Dumping developers into codebase where they must write pure functions (especially in a language without any immutability guarantees) and need a strong understanding of, other more advanced concepts, leads to a painful learning curve and lost development hours.
  • Redux's simplicity is both a blessing and a curse. On the one hand, understanding it is as as simple as understanding a fold / reduce function, on the other, that's basically all Redux gives you. Probably the most common complaint I hear with regards to Redux is the amount of seemingly needless work you need to do to get anything done.
  • In practice the handful of times it made debugging an issue trivial were probably not worth up-front investment.
  • There still really isn't a consensus in the community with regards to which companion libraries you use to do things like even fetch data. From surveying friends, everyone was doing something different.

Conclusion

Judged purely from a productivity viewpoint I'm not confident this is the right approach.

GraphQL, Redux, & Apollo Client

Pros

• Despite my points against Redux above, it is still the most popular/robust solution for global state management in web applications. And while I would like to avoid using it as much as is viable, we will likely still use it for managing some local state (as opposed to remote state,) for things like routing, forms, and possibly more.
• With that said, I think there is a pretty good library for working with remote state in ApolloClient and it integrates with Redux.
• Very easy to use and approach maps well to React's component approach.
• Tooling around GraphQL is fantastic; great developer experience.

Cons

• Unlike the first option, we will not be able to re-use the existing APId resources but it will require us to build a GraphQL endpoint on the backend.
• From a personal standpoint I'm less-familiar with Apollo.
• Unaware of any larger company using it. Albeit, my understanding is that Walmart Labs may be investigating using it(?) Will have to confirm.

Conclusion

This porridge is too hot.

GraphQL + Relay

Pros

• Very easy to use and approach maps well to React's component approach.
• Supported by and used by Facebook and others in production.
• Tooling around GraphQL is fantastic; great developer experience. (GraphiQL, linters, editor integration, and more.)

Cons

• Unlike the first option, we will not be able to re-use the existing APId resources but it will require us to build a GraphQL endpoint on the backend.
• Relay requires a a bit more setup. Also, doesn't play well with react-router and a few other libraries in the eco-system.
• Application is arguably less pure and may be more difficult to reason about using both and Redux and Relay.
• Main golang GraphQL isn't exactly robust. (Albeit good enough until we need to add instrumentation, optimizations, etc.)

Conclusions

I think Relay is described as a 'framework' and while I know this can be a dirty word to some, I think from our perspective it is the option that is going to make us the most productive.

That isn't to say it isn't without it's faults. It's going to require an up front investment (2-3 days to get the initial GraphQL endpoint written) and whatever maintenance costs there may be over time.

[jamesdphillips]

@grepory when you have a moment do you mind reading over the above? Considering the minor time-investment required, I'm wary to make this decision without some form of buy-in from others.

[portertech]

@jamesdphillips can you elaborate on your conclusion, "This porridge is too hot."?

[portertech]

Resource links for reference:

Redux: http://redux.js.org/ GraphQL: http://graphql.org/ Apollo Client: http://dev.apollodata.com/react/ Relay: https://facebook.github.io/relay/

[portertech]

@palourde are you able to spend some time reading over the above? I'd love to read/hear your thoughts. I trust @jamesdphillips and his evaluation, but I too would like to see some buy-in from others that are more informed than myself :)

[palourde]

@jamesdphillips Do you have any feedback about using github.com/graphql-go/graphql for the golang server? I already quickly looked at it in the past and I had some concerns. The first being that on the github page, they state that the project is A work-in-progress implementation of GraphQL in Go. Also, the reviews I've read were not that good and most people recommended to use github.com/neelance/graphql-go instead, which you mentioned wouldn't work with relay :(

[jamesdphillips]

Great feedback, thank you. 🙏❤️

Do you have any feedback about using graphql-go/graphql for the golang server? I already quickly looked at it in the past and I had some concerns.

Yup, it's not perfect.

My main concern when I started this task wasn't found, Relay, etc. it was that two major GraphQL libraries available in Go were seemingly under-developed. However, after some time with both, I think the deficiencies of graphql-go/graphql are irrelevant in the short to medium term.

The main areas in which I see deficiencies the moment are:

• Being a port of facebook's javascript implementation and further being a few minor versions behind, it doesn't have as nice error reporting and some of the newer quality of life improvements that it's ancestor has.
• Doesn't have the same level of hardening. For instance if we were Github and with our publicly available GraphQL endpoint, I might want to evaluate queries for complexity and block them if they are likely to be expensive.
• Missing any sort of middleware or solution for implementing granular instrumentation query executions.
• We cannot use null as a mutation argument as the implementation is lacking support for null literal value at this time.

Outside of the last point, every deficiency I found is largely related to optimization, the ability to accurately make optimizations or arguably minor developer experience features. Since we won't have a strong grasp of what we need to optimize until we have large customers frequently throwing many requests at our API, I think it won't be a major issue that these pieces are missing. And, if were lucky by the time we do someone will have already done the work for us.

most people recommended to use github.com/neelance/graphql-go instead, which you mentioned wouldn't work with Relay :(

We could definitely make it work with Relay, it would really be that much work, but it is work that we wouldn't have to do w/ graphql-go/graphql.

More so, my problems with neelance/graphql-go are:

• You describe your types using GraphQL itself and then write resolvers for any fields separately.
  • IMO this approach is too 'magical', it's immediately obvious how everything works together,
  • and the decoupling of types from resolvers makes things more confusing at first glance.
  • I much prefer that with the other library you describe everything using Go itself. In this way it's arguably much easier to write tests against the schema, reuse code, reason about, etc.
  • Nor does adding a new type/scalar/whatever force a contributor to learn a DSL. They just need to understand Go and have a baseline understanding of GraphQL.
• neelance/graphql-go implementation is also incomplete