[Discussion] Getting Started experience on graphql.org

[praveenweb]

Hey all,

Creating this issue to discuss small but important changes to the GraphQL Getting Started Experience.

When you visit graphql.org landing page, you land on this hero banner.

The top banner here speaks to a client audience (mostly frontend focussed) where benefits of GraphQL for consumption is highlighted.

• Describe your data
• Ask for what you want vs Expose what data you want
• Get predictable results

This needs to address both the frontend and backend audience where the highlights need to balance out what is beneficial for the backend producer.

When you click on Get Started here, it takes you to graphql.org/code.

The hero banner here talks about Code using GraphQL

GraphQL tooling has evolved to allow a different pattern of building GraphQL servers by introspecting a data source (a database or an existing API like an OpenAPI spec) and auto-generating a GraphQL API without writing any boilerplate CRUD code, essentially acting as a compiler. Some examples of such projects are PostGraphile, Hasura, Tuql, Neo4j GraphQL, IBM’s OpenAPI to GraphQL, Mesh’s source handlers, etc.

In summary, two broad approaches to building a GraphQL API have emerged,

• DIY GraphQL: define a GraphQL schema and write resolvers
• Use tools that introspect the underlying source to generate the GraphQL API/schema.

We need to represent these two broad approaches to developers who are looking to get started with GraphQL on the backend.

Happy to start a PR on this, but would love to get more thoughts before I do that.

[praveenweb]

@benjie @Urigo @graphql/content - Bumping this up to get some thoughts.

[doc-jones]

It makes sense to have a path to information for frontend and backend implementations of GraphQL. There are more than these two ways of implementing GraphQL. The BFF pattern is one, for example. Making the changes you suggest would require a broader feedback loop than just adding the tools vendors.

GraphQL provides an API for data exchange which is a description that seems more accurate than calling it a communication pattern. It is an API architecture style with a specification that guides implementation of both the client and the server.

"Code GraphQL" seems to communicate with only a subsection of those who would want to understand how GraphQL and the libraries hosted by the GraphQL Foundation work. I wish I had the time to think through suggestions and recommendations for you to consider, but that's not time I have available just now. I will try to make time for collaborating on these changes in the future.

I will try to circle back here in a couple of weeks.

[benjie]

Sorry for the delay in replying, I wanted to take some time to think about this. My conclusion is that I don't think it's the right framing. There are lots of ways of building GraphQL APIs, and they don't fit neatly into these two categories - for example in PostGraphile you can get part of your schema auto-generated from your database tables, but you can also extend that schema with your own types and resolvers, so it spans both categories. Similarly there are projects like Grats which autogenerate a GraphQL API by type introspection and annotations over your implementation code... so effectively you've written the resolvers and the GraphQL types just "fall out" of that automatically (this is the kind of thing Facebook does internally, I think?). Does a system that uses some code generation fall into the autogenerated camp just because it has some automation, or is it DIY even though you're not writing all the resolvers by hand?

I feel like artificially partitioning solutions into categories like this would act to limit innovation, and may lead to poorly researched dogmatic opinions such as "all autogenerated APIs are bad" or "writing a GraphQL API by hand is redundant, it should be autogenerated" whereas in the real world there isn't a one-size-fits-all solution to API development, and all solutions have pros and cons.

I definitely agree that the homepage should do a better job of speaking to the backend audience as well though.