
Principled GraphQL - debergalis
http://www.principledgraphql.com
======
andrewingram
The main argument I have against "One Graph", is that it's not that uncommon
to have two (or more) quite distinct views of the world.

At my last job, we were building a social shopping app. Behind the scenes,
products were versioned so that we could deal with disputes related to
attempts to defraud customers. This (along with several other things) meant
that the logical internal abstraction of the data model for things like
dispute dashboards was considerably more complicated compared to an
abstraction that made sense for the clients (apps and website).

If we only had one graph, all the clients developers would have to develop
around a data model that was far more unwieldy than they needed. But with two
graphs, the world was a lot simpler (at the cost of having to maintain two
graphs).

~~~
PaulHoule
The RDF world has conclusively proven that there is more than "One Graph".
(e.g. people try to make "One Graph" and their projects die; try to make as
many graphs as there are points of view and the sailing is smooth)

~~~
andrewingram
In the case of GraphQL, I'd be interested in seeing strategies for multiple
graphs within a single codebase. Essentially being able to produce different
schemas based on config. I know that superficially it's as simple as some "if"
statements, but I'm curious about the maintenance/scalability side of it.

~~~
PaulHoule
How about having N base graphs and the ability to make unions of the graphs,
as well as other kinds of algebra.

It is relatively easy to do this in the RDF world since the graph is composed
of individual facts which may or may not be in a particular graph.

~~~
mhuffman
Which triplestore are you using that gives great front-end performance at
load?

~~~
PaulHoule
None of them are really "great". I get acceptable results with OpenLink
Virtuoso if I give it a lot of RAM, tweak the configuration, and baby it when
needed.

------
topspin
I'm experiencing some frustration with this. Click on this
principledgraphql.com site and you find it's 'Apollo.' Nearly everywhere you
look on the Internet regarding GraphQL you find 'Apollo' being injected.

I'm using GraphQL in production systems. One is Node (graphql-js) and another
is Java (graphql-java.) I read the GraphQL specification and adopted the
reference implementation and it works great. Am I missing some enormous value
by naively just using GraphGL without involving Apollo?

That is a sincere question. What is the deal here?

~~~
unleashit
It's called marketing and they're pretty good at it. They do provide some
useful tools however if you want to use them and don't just blindly follow the
docs (which are selling you on things you may/may not need).

~~~
wawhal
Apollo's marketing game has been ridiculously on point. They are the only
GraphQL client in the ecosystem that is fully compatible with any GraphQL
compliant server [0]. And since it is pretty good, whenever one has to
talk/market/propose anything about GraphQL in the community, they end up
cross-marketing for Apollo.

[0] Relay has its own spec and can be used only if the server supports it.
Other GraphQL clients are either not well maintained or do not support as many
features as Apollo does (caching, subscriptions are two features that come to
mind)

~~~
andrewingram
FWIW: You don't have to follow any of the Relay spec to use Relay. Though
you'll lose many of the benefits if you don't at least use globally unique
'id' fields on each major type. Connections are optional, the node interface
is optional.

------
samblr
Let's admit it - GraphQL is NOT simple-and-simply an easy replacement to REST.

I see it's advantages of having auto-documentation for each API. Thumbs up
here.

Having said that, the amount of hoops one has to jump before completely
adopting it - makes it 'meh'. There are lot of things : cache (clien-and-
server), n+1, apollo (why?), deeply nested queries, schema stitching. The
amount of patch work one needs to learn is not worth it.

~~~
danpalmer
> Let's admit it - GraphQL is NOT simple-and-simply an easy replacement to
> REST.

I disagree. GraphQL is more difficult to implement than "bad REST", but
probably easier to implement than "good REST", partially because there's very
little tooling around good REST implementations.

If you just want JSON over HTTP with some status codes, then sure GraphQL is
loads more work, but that's definitely not REST.

~~~
spiritcat
"If you just want JSON over HTTP with some status codes"

yes this

Qualifier: have not been able to use graphql yet, and I'd still like to try it
out at least before making and judgements

~~~
danpalmer
GraphQL costs a lot more to do, but also gives you a lot more.

Just some benefits we've seen:

\- Automatic codegen in the client removes a lot of boilerplate.

\- Verification of schemas in CI makes sure we don't "go backwards" on the API
inadvertently.

\- Documentation tooling that makes it easy to show API structure.

\- Easy to generate schemas automatically from underlying data models in the
backend service (database tables, ORM models, enums, etc).

\- Great type safety compared to JSON over HTTP.

------
avitzurel
I disagree with the notion of `One Graph`.

We have multiple "gateways" for multiple backend services.

We have our main application that has one graph and we have multiple internal
applications each owns its own graph.

I don't think the main application needs to know about the other internal
graphs, nor should it have access to it (it should not even discover it).

~~~
bartq
They advocate one graph, because it's too hard to merge graphs in parent-child
(many-to-one, many-to-many) relationships (recursively) in a flexible way.
This is purely because of technical limitation of GraphQL IMO.

~~~
nevir
An alternative architecture (following the BFF idea):

* Non-GraphQL services (speaking REST, gRPC, whatever) * GraphQL gateways, owned by frontend teams/applications.

E.g. each frontend team/application owns its own schema owned by these teams.
They can compose the backend services however they wish—and whatever is the
most natural representation for their domain.

~~~
debergalis
[author here]

Yup, we see this pattern a lot. You get the benefits of fewer bytes on the
wire, typed APIs, elimination of data fetching code, etc.

But it leaves a lot on the table. The bigger wins come when new features can
draw from all your data (in unanticipated combinations) without new API or
services development, when you can make new data available for every team's
use just by plugging it into the central graph, and when you have a birds-eye
view of exactly how all your data is being used so you know where to make
further investments.

~~~
nevir
Yeah, I'd also add that it is a huge help in ramping up new devs when
understanding your schema.

------
pseudoramble
One question I have is with the "One Graph" idea. I get the principle, and it
does seem like it would be nice. However, it's hard for me to imagine what
this looks like in practice.

I haven't done anything with GraphQL in a few years. But when I did, we
basically had several teams in a part of our organization (one of many in a
huge giant megacorp) which built an API with GraphQL. We shared that code base
and did the changes in it we needed for different parts of the graph.
Sometimes it was fine, and sometimes it didn't go so well (unexpected issues,
unexpected deployments when a team didn't prepare properly, etc). So it was an
OK idea, but it caused some friction.

A decent of the problems were communication between teams of course. But even
if communication was as good as one could imagine, it seems like this model
would cumbersome at some point. And I can't imagine it spanning our entire
organization, much less our entire megacorp across the board.

So assuming what we did wasn't good, what is a way you might make this work?
Do you have a single code base like we did and just be more disciplined? Do
you have a project whose job is to stitch together other schemas and pull in
submodules? A monorepo for the entire company? Do you actually limit what the
idea of the company is at some point to limit what the scope is that this
should cover?

This turned out to be more of a ramble than anything. Oops.

~~~
debergalis
[author here]

> So assuming what we did wasn't good, what is a way you might make this work?
> Do you have a single code base like we did and just be more disciplined? Do
> you have a project whose job is to stitch together other schemas and pull in
> submodules? A monorepo for the entire company? Do you actually limit what
> the idea of the company is at some point to limit what the scope is that
> this should cover?

I think these are great questions. One approach that looks promising is the
idea of modular schemas that can be stitched together into a larger graph.
Quite a few large organizations are doing this now. I recommend watching a
recent talk by Martijn Walraven for more on this idea:
[https://www.youtube.com/watch?v=OFT9bSv3aYA](https://www.youtube.com/watch?v=OFT9bSv3aYA)

~~~
orta
We do this at Artsy in production too, here's an overview of how it works for
us: [http://artsy.github.io/blog/2018/12/11/GraphQL-
Stitching/](http://artsy.github.io/blog/2018/12/11/GraphQL-Stitching/)

------
gnat
Summary: have one company graph, implemented as federated implementations from
different teams, with a registry for tracking the (iteratively evolving)
schema. Use per-client access permissions and structured logging,
incrementally improving performance as usage grows. Data graph functionality
should be a separate tier rather than baked into every service.

------
vanwalj
We should probably add another point which is "you probably don't need Apollo
tools".

I'm using GraphQL in production since 2015 and I feel like the only Apollo
contribution to the ecosystem was pushing lot of marketing content around
their hacky tools and "best practices", leading teams to poorly designed
backends.

~~~
danpalmer
Yeah, I haven't seen a lot that has been particularly useful from Apollo so
far.

They supposedly have a slightly different recommended way of doing the things
Relay tries to do, but it's poorly documented and only compatible with Apollo,
whereas the Relay spec is relatively clear (just the spec, I haven't used the
Relay library).

Also they seem entirely JS focused. Our backend is Python and our frontend so
far is Swift. They have no Python tooling, and their Swift codegen has a lot
of issues, our iOS devs use it pretty reluctantly and replace a lot of parts
of it, and even that tooling is all in JS, not Swift, which means our iOS
builds suddenly need Node, Yarn, NPM, etc, a whole load more complexity,
caching, and so on.

~~~
RussianCow
I'm currently working on building an open source library for building backend
GraphQL APIs in Python. I'd love to hear your use cases! My email is in my
profile, if you're interested.

------
lsjroberts
We've been working on doing something similar to create "one graph" at my job
(though using our own library instead of graphql [1]).

There are definite difficulties to doing this, you need some strong cohesion
between teams. If you try to do it in an agile manner, you're going to end up
with a lot of duplication with minor differences. You'd need a way to flag
existing similar data when trying to add new branches and nodes.

Our hope is to make our graph explorable and interactive so teams we don't
have direct contact with, often in other countries, are able to find the data
they would be interested in and see immediately how to read it out.

[1] [https://dwstech.github.io/muster/](https://dwstech.github.io/muster/)

------
jeswin
I think the single graph idea is impractical in any large organization. Every
centralized model deteriorates over time due to many reasons: time pressure,
carelessness and bigly varying competence levels in federated teams. A couple
of years down the line everyone will hate it, and it'll be too big to discard.

Independent team structures and microservices based architectures are
acknowledging that such monoliths are impossible to build and maintain.

~~~
AlecAivazis
The point of federating your schemas across different services is that you can
achieve the single graph that represents the organization without having the
separate parts step on teach other. It doesn't discard microservices, it
embraces them.

------
mst
There's nothing that says "we're really good at making front end development
easier" like a website where even after I click into the main frame it
completely fails to respond to up/down/pgup/pgdown ... I understand the whole
"should work on mobile" thing but it should also bloody well work on a desktop
too :(

~~~
debergalis
Thanks, looking into it. I agree and I hope we're able fix this. We're moving
all of the Apollo docs to the same system. It's built on Gatsby, which uses
GraphQL under the hood.

~~~
mst
Cheers. I get really cranky about my keyboard not working (twitter's web UI
manages to break it under a bunch of circumstances, which aggravates me at
least once a week) but I'm well aware that there's always a billion things
that need doing :)

------
tlivings
Single graph: Large companies often do not have a single graph. Different
experiences and use cases require necessary variation in how teams surface
data and do experimentation independently from other teams.

Federated implementation. Implementation being spread across many teams is
important, but if that is through federated services being reused by multiple
teams, it can create brittle dependencies.

Track schema in the registry: It's difficult to have a single source of truth
when it is unable to display the variation based on #1 comment. I don't think
anyone has solved this well for really large systems. Good principle but hard
in practice!

I think it is really hard for a VC backed company selling a product to
describe principles without being biased. This feels very biased toward
selling their product.

------
ewittern
Principle 8 mentions "demand control", including "estimating the cost of a
query before performing it". This is very much in line with GraphQL API
Management work we are doing at IBM Research. I recently wrote about this:
[https://www.ibm.com/blogs/research/2019/02/graphql-api-
manag...](https://www.ibm.com/blogs/research/2019/02/graphql-api-management/)

I wonder about the other proposal for demand control, namely that untrusted
users "should only send queries that have been preregistered by the
authenticated developer of the app". To me, that seems to somewhat negate a
great advantage of GraphQL, namely giving clients more flexibility in deciding
(on the fly) what data to fetch/mutate.

------
jcroll
is graphql something anyone really needs unless they're facebook

~~~
lopatin
While using GraphQL does have some benefits when dealing with a massive amount
of users, that's not the reason most people choose to use it. GraphQL is
simply a drastically different (and IMO better than REST) model for clients to
talk to servers.

~~~
sheeshkebab
I don’t think it is - mutations (and state management) are the biggest issue.
It’s ok for reads though, although even there tooling for rest is better.

~~~
RussianCow
> I don’t think it is - mutations (and state management) are the biggest
> issue.

How so? I don't think GraphQL mutations are any worse than their REST
equivalents, especially once you get more complex than "update these fields on
this entity".

------
dfischer
Just wanted to throw out that this is cool amongst the critical feedback.
Thanks Apollo and GraphQL for pushing the boundaries. It was fun using it when
it was needed. Recently moved onto other pastures but solid progress!

------
barberousse
Anyone else's job have Cisco Umbrella flagging this page as possibly a malware
distributor?

------
alex_berg
I think the author doesn't understand what "principled" means.

