
How to GraphQL – A Fullstack Tutorial for GraphQL - sorenbs
https://www.howtographql.com/?v1
======
nikolasburk
Hey everyone

We're super excited to finally launch this resource that we've worked on
together with amazing members of the GraphQL community! The goal of How to
GraphQL is to provide an entry-point for all developers to get started with
GraphQL - no matter what their background is.

The whole site is open-source and completely free to use! If you want to
contribute a tutorial because your favorite language is still missing, please
get in touch with us!

Here's the official announcement blog post on the Graphcool blog:
[https://www.graph.cool/blog/2017-07-11-howtographql-
xaixed1a...](https://www.graph.cool/blog/2017-07-11-howtographql-xaixed1aa9/)

If you find a bug or another problem, create an issue or submit a PR on the
GitHub repo:
[https://github.com/howtographql/howtographql](https://github.com/howtographql/howtographql)

Follow us on Twitter to be informed about new content that's added to the
site: [https://twitter.com/graphcool](https://twitter.com/graphcool)

------
sayurichick
I like USING GraphQL (for existing services), like Github's API.

However, 99% of the tutorials on graphql , this one included, fail to show a
real life use case. What I mean by that is a working Example of a SQL database
from start to finish.

So this tutorial was very cool, but not very useful. Just like the rest of
them.

I've yet to find a recent tutorial that covers full stack node.js +
PostgreSQL/MySQL + whatever front end. It's always MongoDB or only covers the
concepts of GraphQL.

~~~
slaymaker1907
The problem with using a relational database with GraphQL seems like you need
to solve the object relational mismatch. I think in that case you'd be better
off writing a library for parsing SQL then putting a secure layer over it that
limits what SQL is allowed.

Ideally, you'd be able to just handle these security issues with the database
directly through views and permissions, but as far as I know there is no
database with enough permissions controls for this.

~~~
vosper
What about using GraphQL implies that you're trying to map objects from the
database? As far as I know you can just query for the fields you want (with
whatever joins you might need, or subqueries, or calls out to some other
system) and return them to the client.

~~~
slaymaker1907
It's doing object mapping because it is coercing everything into JSON. Looking
at the language, you see the usual suspects of strange cyclic objects for
representing relations typical of ORMs. These systems tend to struggle when
dealing with things like many to many relationships, non-total relations, etc.
To give it credit though, I do like that GraphQL forces a firm separation
between remote and local data, though I'm sure there are already libraries for
GraphQL trampling over that separation.

------
Cieplak
Just wanted to give a huge shout-out to PostgREST:

[https://postgrest.com](https://postgrest.com)

[https://github.com/begriffs/postgrest](https://github.com/begriffs/postgrest)

You can get many of the benefits of GraphQL using postgrest's resource
embedding:

[https://postgrest.com/en/v4.1/api.html#resource-
embedding](https://postgrest.com/en/v4.1/api.html#resource-embedding)

We're using it in production.

PS: To be clear, you can't expose it directly to your users. We wrap it in a
proxy service that provides authentication and authorization, and parses and
transforms the users' URL queries destined for PostgREST. We also apply some
transformations to the data coming back from PostgREST, such as encoding our
internal UUIDs. It may sound complicated, but it's actually only about 200
lines of Erlang.

~~~
ryeguy
IMO modeling your api directly off of your database tables is often an anti-
pattern. One of the biggest mistakes I see people make is assuming their api's
data model has to match their database's. It's common to introduce resources
on the api side that may not have their own table in the database. For
example, you could have a table that has a "type" flag (to model some kind of
inheritance), but on the api you expose these as separate resources. Or you
could have a larger resource on the api, but it's actually backed by several
tables.

Graphql is also more generic and allows you to fetch from multiple data
sources. These could be databases, apis, or wherever. You write code that
fulfills each column and graphql assembles a single object.

I could see postgrest being ok for prototyping or simple apis, but it seems
like one of those things that you'd grow out of eventually.

~~~
Cieplak
If you treat PostgREST as an ORM, then you can easily decouple the database
data model from the API representation. I imagine there are scenarios in which
PostgREST would outperform certain ORMs implemented in dynamically-typed
languages.

~~~
rizhabib
This is exactly my usecase. I replaced my NodeJs ORM layer with PostgREST and
express apis layer with Aws ApiGateway.

------
xmatos
Why use GraphQL? Why not simply expose one endpoint that takes a sql data
parameter, queries the db and return the result set as json?

Yes, you'd have to setup db security to allow those db commands to run only
selects and restrict which tables are allowed to be queried.

How can using a new json query language, without any server libraries
targetting relational databases be better than that?

How much work would be envolved to implement this on the server side and for
what, exactly? to allow frontend devs to query without exposing separate
endpoints?

Client-server applications should not run business code on the client. The
only code that should run on the client is the UI's.

Sorry, this is simply wrong.

~~~
arcticfox
What happens when your backend isn't SQL? Then you'll need to accept a
different query language as well. Wait - maybe those could be abstracted into
a single query language? Ah, it's GraphQL!

To your other points:

* no matter what you do to expose an API you have to set up security

* there are already server side solutions that help enormously with implementing your own endpoint

* I don't see the logic behind your client-server opinion. You seem to say that the server should be defining the data that the client needs.

~~~
xmatos
Regarding the last point, yes, that's what I'm saying. And it's not a matter
of opinion, but of decades of computer engineering best practices.

Your app's UX will depend on how much code runs on the client. It can vary
from a dumb terminal, like classic web applications, where everything runs on
the server, to smart or rich clients, where some code do run on the client,
but is always related to the UI. In a client-server application, your app's
logic should always run on the server.

I've worked on desktop client-server apps where the application logic was on
the client and the server was mainly the database. It works, but you might end
with clients with different versions trying to access the DB and you don't
want that.

That's what server validation means. You should never trust clients. You
shouldn't build a web app, which is a client-server app, entirely on the
client. It's like reverse best practices. It will bite you.

Regarding having something else than sql, how much effort would be necessary
to build a graphql server library that abstracts whatever you have on the
server? Would you build something and release it to your clients with that
level of maturity? And for what?

------
renke1
I recently started using GraphQL and I love.

The best thing about GraphQL is having a standard interface for queries (and
more) and all tools that built upon it (such as Apollo). To name a few
existing and upcoming (?) features from Apollo: Query batching, real-time
updates (WebSockets + subscriptions), caching, optimistic UI, polling,
pagination, live queries and many more.

Also, GraphiQL is pretty cool, too, basically Swagger for free.

------
slaymaker1907
I've looked a bit through the GraohQL syntax. While it is an immense
improvement over plain Rest, I dislike the abuse of JSON as a query language.
I think it would be better if it were a true DSL like SQL or some sort of
Lisp.

Instead of allPersons, I think it would be cleaner and easier to understand as

(all Person)

Which makes the generic nature of "all" explicit.

~~~
djmashko2
The thing is that the "all" is actually _not_ generic in this case. The
GraphQL server implementor has to specify a field called that specifically.

------
notheguyouthink
What I've not understood about GraphQL is how to map it to My/Postgre/etc SQL.
The info about resolving specific fields seems .. complex, and difficult to
optimize tom say, reduce SQL calls.

Is there a library that, say for Golang, helps translate a GraphQL Query into
SQL statements to actually get the data?

~~~
raarts
I've read comments here on HN that the server side of graphQL is notorious
hard to implement, the resolvers end up being really complicated or slow.

Anyone care to comment from practical experience?

~~~
strken
I've implemented three graphql backends - one wrapping a rest api, one
wrapping mongo, and one wrapping postgres. The key, just like in rest, is to
keep the different layers isolated. If your resolvers never do anything more
complicated than parsing arguments and passing them to the next layer, it's
hard to make them complicated. One project parses the graphql ast and there's
a small performance gain from that, and another batches identical requests
with Facebook's DataLoader library, but those are done behind the scenes and
don't end up polluting the resolvers, and to be honest they probably weren't
necessary.

Most of the resolvers end up looking something like

    
    
      {
        type: FooType, 
        args: {
          fooId: GraphQLString,
          ...paginate.args,
        }, 
        resolver: createRESTResolver(
          ({ fooId }) => [`${services.foo}/:fooId`, { fooId }] 
        ).use(paginate), 
      }
    

but if I was doing it again I'd probably abstract the creation of the entire
field rather than just the resolver.

------
alexchamberlain
It's fantastic to see a tutorial that separates the frontend from the backend.
As someone that _doesn't_ work in web technologies, it can be tough to follow
basic tutorials or take them to the next level when you're trying to
understand node, npm and webpack, as well as the concept you want to learn:
GraphQL, which although hyped, does look like it brings substantial value to
the table.

~~~
aaron-lebo
If you are a starter don't worry about it at this point. A good REST API and
understanding of how that works is a really good foundation for web
development that you can take with you from language to language and project
to project. This is a cool but still relatively niche technology.

~~~
alexchamberlain
My interest in GraphQL has a few different layers: it's a different querying
paradigm, in the same way that REST and RPC paradigms are different; what are
the pros and cons? How do you optimise services throughout your stack to
handle load that is - in theory - of an unknown pattern, but in practice, will
be of certain shapes? Furthermore, if we divide SOA/microservices into several
tiers - separating UI services from backend services - does GraphQL fair
better than more traditional paradigms? How do we "merge" GraphQL schemas?

Whilst I agree it's niche now, not many new paradigms come along and not many
of them have so many questions that can be asked, so there has to be something
interesting there.

------
Dirlewanger
I've only given a cursory look into it, and with regards to building a JSON
API in Rails (of which the many extant standards and their Rails libraries are
still immature), is this just another fad, or an actual API standard that has
staying power? It seems like the latter, but given that it's Facebook-backed,
as soon as they get tired of it, they could pull a Google on it.

~~~
pselbert
There is a practical, functional GraphQL spec that has multiple client and
server implementations. Regardless of whether Facebook continues to develop
clients or maintains stewardship of the spec, GraphQL has a lengthy future
ahead.

------
soflete
I have recently started learning React and I am following the lessons in
www.hotwographql.com. I am trying to decide which GraphQL library to use for
the practical exercise. Should I go for Relay or Apollo?

Also, I have been working as an Android developer for the last couple of
years, and I was wondering how similar are the React and Android
implementations of Apollo.

~~~
nikolasburk
How to choose between Relay & Apollo is one of the most common questions
people ask when they get started with GraphQL! In general, it definitely
depends on your project and what you're optimizing for.

Relay is very mature and heavily optimized for performance, however, it's not
very easy to understand and comes with a notable learning curve.

Apollo on the other hand is a community-driven effort to build a very flexible
GraphQL client that still offers a powerful and intuitive API.

I'd actually suggest you try to go through both tutorials on How to GraphQL
and see which one feels better for you :)

PS. In case you weren't aware of it - the second GraphQL Radio episode had Lee
Byron and Joe Savona (both from Facebook/Relay) as well as Sashko Stubailo and
Jonas Helfer (both from Apollo) as guests: www.graphqlradio.com

------
miclill
GraphQl really seems to be a step up from REST. The complexity of the
client/server-libraries will increase but that's ok.

If I look at graphql-java I see:

\- "The Java implementation of DataLoader is unfortunately still in the
making."

\- "While graphql-java does parse subscription requests, its support at the
moment unfortunately stops there"

Seems it's not ready yet.

------
shroom
Awesome resource! I've been playing around with GraphQL on a Node/React+Apollo
project and found it very useful and fun to use.

My background with backend is mostly PHP. Any good plans on adding PHP guide
to backend section or is there no good GraphQL-server/implementation for PHP?

~~~
jasonbahl
I can't speak to the entirity of your question, but the last part I will
address: "is there no good GraphQL-server/implementation for PHP"

There are 2 good PHP servers:
[https://github.com/Youshido/GraphQL](https://github.com/Youshido/GraphQL)
[https://github.com/webonyx/graphql-php](https://github.com/webonyx/graphql-
php)

It seems like the majority of the graphql-php community has rallied around the
Webonyx implementation, including myself for my WPGraphQL project, a free open
source WordPress plugin that brings a GraphQL API to WordPress
([https://wpgraphql.com](https://wpgraphql.com))

As the maintainer of WPGraphQL, I'd be interested in adding a section to the
HowToGraphQL resource specific to using GraphQL with WordPress, but haven't
had any official discussions with the maintainers of the project yet.

There are also implementations for Laravel and other projects, using that
library.

~~~
shroom
Thanks a lot this was exactly what I was looking for :) sorry if the question
was a bit fuzzy.

------
bdibs
I just read more and played with GraphQL just the other day, and it's really
an amazing and powerful tool.

Save requests and bandwidth, no need for explicit version control, and to top
it off an easy to use syntax? Sign me up!

I'll definitely be using this in future projects.

------
j_s
I am curious to here about any experiences implementing a GraphQL backend in
production on .NET (non-Core) + SQL Server. Even React feels left out here in
my neck of the woods.

------
schrockn
Great job. Awesome to see all the focus on documentation and conceptual
explanations. Clear messaging and spreading understanding are just as
important as the tech.

------
zimme
Awesome! I'll share it with GraphQL Stockholm.

------
yks
Is GraphQL substantially better than OData (created 5 years earlier)?

------
ai_ia
Exactly what I was looking for. Thanks team behind this.

------
Huvik
Nice job! Great source for learning Graphql :)

------
chaaau
Heyhey! I heard a lot about GraphQL before, but I'm not quite sure what it is.
Is it similar to Neo4j?

~~~
nikolasburk
Hey! That's actually a pretty common misconception people have about GraphQL
when they first hear about it - however, GraphQL definitely is not a Graph
database (as is Neo4j). In fact, it's not even a database technology, despite
sharing the same suffix with SQL!

GraphQL is a query language for APIs - so, the closest you could get is to say
that GraphQL is an API technology! It defines a specific request/response-
format for client-server communication that's extremely flexible, simple and
efficient. GraphQL is also independent of the transport protocol that's used
(though mostly that's HTTP today).

If you have a good idea about what an API is, you can read the second chapter
of "How to GraphQL" where we highlight technical differences between GraphQL &
REST: [https://www.howtographql.com/basics/1-graphql-is-the-
better-...](https://www.howtographql.com/basics/1-graphql-is-the-better-rest/)

------
justforFranz
The GraphQL has a diversity problem. :)

