Michelle Garrett - Build the API you want to see in the world (with GraphQL) - Codemotion Berlin 2018

BUILD THE API
YOU WANT TO SEE
IN THE WORLD

I’m going to talk to you
about GraphQL.

This is not a serious
deep dive into how
GraphQL works.

This is a talk about the
problems GraphQL can
solve in the real world.

Why did I choose to use
GraphQL?

A story of LIBERATING
an application from the
grips of a 3rd party API

...and finding happiness
with GraphQL <3

I am a Software Engineer at
Condé Nast International in London.
I organise Node Girls.
I GraphQL.
@msmichellegar

1. GRAPHQL + ME
2. GRAPHQL + YOU
WHAT I’LL TALK ABOUT

GraphQL is “a query
language for APIs”.

GraphQL is a language
for requesting remote
data.

GraphQL is a syntax for
asking for information
from a server.

With REST you have
multiple endpoints.
eg. /articles /galleries

GraphQL has a single
multi-purpose endpoint.
eg. /graphql

With REST the endpoint
gives you a predefined
set of data.

GraphQL gives you
exactly what you ask
for. No more or less.

There is a “schema” that
tells you all the fields
you can request (and
their types).

To request data you write
a “query” describing
what you want.

*GQ is not a magazine about GraphQL

WHAT THE APP
USED TO LOOK LIKE

API
An API for the
content
management
system (CMS)
that our editors
use to write
content.

1. A lot of our
components were tied
very specifically to the
API response.

const Title = ({ apiResponse }) => (
<div>
<h1>{apiResponse.title}</h1>
</div>
);

If the API changes, you
have to update your
components.

const Title = ({ apiResponse }) => (
<div>
<h1>{apiResponse.head}</h1>
</div>
);

It’s less readable. It’s
not clear what data
your component needs.

Our components know
too much about their
context.

Context: where data
comes from, structure
it’s fetched in, all data
available in the app.

Ideally we’d have a few
components that know
context, while most
have no idea.

PRESENTATIONAL CONTAINER
const Title = ({
text
}) => (
<div>
<h1>{text}</h1>
</div>
);
const Article = (data) => (
<article>
<Title text={data.title} />
</article>
);
export default compose(
withArticleData
)(Article);

PRESENTATIONAL
Knows nothing
about context.
No state or
dependencies.
Just takes in
data and
displays it.
const Title = ({
text
}) => (
<div>
<h1>{text}</h1>
</div>
);

const Title = ({ text }) => (
<div>
<h1>{text}</h1>
</div>
);

CONTAINERKnows about
context.
Often generated
by HOC.
Provides data to
presentational
components.
<article>
</article>
);
export default compose(
withArticleData
)(Article);

<article>
<Byline author={data.author} />
</article>
);
export withArticleData(Article);

We did not enforce this
strictly enough! Our
components knew too
much :(

Ideally even container
components don’t know
about the 3rd party API.

Our components
needed refactoring.

2. We sent a lot of data
we weren’t using to the
client.

Confusing clutter! We
don’t need it, why is it
there?

It can affect
performance. The
browser is downloading
unnecessary stuff.

It can be a security risk.
What if the API
developer introduces a
sensitive field?

Moral of the story: we
should not be sending
all this data to the
client!

3. If we switched data
sources, we’d have to
completely rewrite our
entire application.

Pretty much everything
in our app was closely
tied to the API.

If we switched CMS,
we’d have to throw
away our app and
rewrite it.

Technology changes,
your app should be
resilient!

It is a business risk to
couple your application
to a third party service.

We needed to
consciously decouple!

4. The API was difficult
to work with: it had
some quirks that we
didn’t understand.

Disclaimer: this is the
case with ALL third
party APIs.

It was not built with
our specific use case in
mind (can you believe?)

Field names did not
always make sense to
us.

There was SO MUCH
DATA. More than we
needed.

Some data was not in
the format we
required.

body: “## Miranda Kerr
Hochzeits-Make-up”

There was not always
documentation.

(Documentation is hard
when it is done by
humans)

Third party APIs will
never be perfect!

But we needed to work
better with the API in
our application.

5. We were fetching
data in complicated
ways from deep trees in
the API every time.

/article/meghan-markle
/api/article/meghan-markle
/api/article/meghan-markle/history/publish
/api/contributor/michelle-garrett
/api/category/fashion
/api/recommendations?id=”meghan-markle”
/api/article/recommendation1
/api/article/recommendation2

It was cognitive
overload trying to
remember where to get
which data.

We had to navigate
complex relationships
between objects.

We had to make
multiple requests in our
main application to get
the data we wanted.

If you make multiple
requests client-side,
it’s not performant.

We had a spike, and
prototyped different
solutions to our
problems.

One was a refactor
based purely on domain
driven design.

API
REACT
SSR
Redux
Hapi
Business Logic

API
REACT
SRR
Hapi
Apollo
Client

REACT
SRR
Hapi
Apollo
Client
API
Business Logic

The GraphQL ecosystem
has tools that generate
documentation from
your schema.

Our documentation is
now useful and stays up
to date with no effort.

We now know for sure
what data we can
request for our client
side application.

2. We no longer have to
fetch data with multiple
requests in our main
application.

Now we get data in a
clear, consistent way.

(We still have to make
the same requests, but
they now happen in the
GraphQL layer).

Our React application
doesn’t have to know
about it.

Our lives are much
easier now that we only
have to think about one
query.

3. It encouraged good
patterns of structuring
our app.

We started fetching only
the data we needed.

We stripped all business
logic out of our
components
(separation of concerns)

We used field names that
made sense, instead of
using what the API gave
us.

Our UI is no longer tied
to the API.

Disclaimer: We could’ve
done this WITHOUT
GraphQL

With more discipline, we
could have avoided some
of these problems.

There are programming
patterns that encourage
these principles.

Domain Driven Design
Hexagonal Architecture

GraphQL enforces these
patterns without
requiring developers to
police it themselves.

GraphQL allows you to
follow these patterns
without having to think
about it.

4. We have the insurance
that if we ever need to
change our data source,
most of our app will not be
affected.

Scenario: Condé Nast
might decide to switch
its CMS to Wordpress

Changing data sources
will only affect the
GraphQL layer which
shields the React app.

The impact is limited to
updating the functions
that resolve data for
each field in the schema.

The API we use might
completely be
rewritten but we are
resilient

We can now react more
easily to technology
changes. Our application
won’t be devastated.

1. You have a set of data
that needs to serve
multiple applications.

GraphQL is
“product-friendly”.

It has a lower barrier to
entry for new
consumers to the API.

Because it reduces the
burden on consumers to
perform logic.

It does not enforce a
specific way to
consume an API.

It gives consumers the
flexibility to request
data in the way they
want.

{
category(
slug: "beauty"
) {
articles (limit: 10) {
title
image {
url
alt
}
}
}

{
category(
slug: "beauty"
) {
images (limit: 10) {
url
alt
}
}
}

Your applications can
be totally different, but
seamlessly use the
same set of data.

2. You’re building an
application that uses
multiple data sources.

Scenario: Condé Nast
introduces an extra data
source: a shoes API for a
feed of shoes.

You can build a
GraphQL layer to fetch
data from all your
sources.

Combine data from
anywhere, but only
interact with one
interface.

Note: GraphQL and
REST are not mutually
exclusive!

You can get data from
lots of places (including
REST APIs) and smoosh
it all together.

Possible data sources:
- REST APIs
- Other GraphQL APIs
- A database
- JSON in your file system

Your resolver functions
will handle all the
complication behind
the scenes.

Meanwhile on the
frontend, you’re living
the sweet GraphQL life.

3. You’re stuck with a
legacy API.

Does your application
rely on a really old API
with an ugly interface?

You can design and use
a modern interface that
you actually like.

4. You want to enforce
structure in your code
base.

GraphQL encourages
good habits.

It will help you
separate your concerns.

It will encourage you to
remove logic specific to
3rd party APIs from
your client application.

5. You’ve built your
REST API like a
pseudo-GraphQL API
anyway.

Do you have endpoints
that fetch fields based
a query param?

/articles
/articles?
slug=meghan-markle
&fields=title|author|body

...it’s basically already
GraphQL.

6. Because it’s fun and
everyone else is doing
it* :)

6. Because it’s fun and
everyone else is doing
it* :)
*This isn’t the only reason you should choose a tool

- It gives you instant documentation.
- It’ll stop you having to make multiple
requests for data.
- It’ll help you to better structure your
code base.
- It shields your app from changing data
sources with a consistent interface.
WHY GRAPHQL IS NICE

- You have a set of data that needs to serve
multiple applications.
- You’re building an application that uses
multiple data sources.
- You’re stuck with a legacy API.
- You want to enforce better structure in your
code base.
- Your REST API already fetches fields based
on a query param.
REASONS TO USE GRAPHQL

I HAVE DELUXE STICKERS
@msmichellegar
THANK YOU!

Michelle Garrett - Build the API you want to see in the world (with GraphQL) - Codemotion Berlin 2018

Recommended

Recommended

More Related Content

What's hot

What's hot (16)

Similar to Michelle Garrett - Build the API you want to see in the world (with GraphQL) - Codemotion Berlin 2018

Similar to Michelle Garrett - Build the API you want to see in the world (with GraphQL) - Codemotion Berlin 2018 (20)

More from Codemotion

More from Codemotion (20)

Recently uploaded

Recently uploaded (20)

Michelle Garrett - Build the API you want to see in the world (with GraphQL) - Codemotion Berlin 2018