GraphQL research summary

Digital Transformation Specialist
GraphQL
Research Summary
7th February 2019 – Yaroslav Gontar

© 2019 Objectivity Ltd
Introduction to GraphQL
Developed by Facebook in 2012, GraphQL is a query language for APIs
and a server-side runtime. It allows to fulfil queries by using a type system
you define for your data.

Why use GraphQL instead of REST API?
 To fetch data you typically need to access multiple endpoints
with fixed data structures. This can result in over- and under-
fetching.
 To fulfil a complex query that fetches data according to some
relationships, you have to create multiple requests and build
the related data into the initial response (or modify URLs).
 Commonly REST endpoints are structured according to the
needs of your app. This stifles the possibility of rapidly cycling
through different front-end iterations.
 Because of the data structures, it is difficult to know exactly
what kind if information each client typically needs.
 REST is a go-to solution for some uses, but in other cases it’s
too rigid. Although you can do almost anything using REST
API, the effort of implementing some functionalities is not
worth it. Why do it if GraphQL is already there?
Like most technologies, REST is not perfect and has some drawbacks.
Some of them, solved by GraphQL, are:

Using GraphQL in a GitHub API – a real life story
 Despite all the information we provided, we heard from
integrators that our REST API wasn’t very flexible. It
sometimes required two or three separate calls to assemble a
complete view of a resource. It seemed like our responses
simultaneously sent too much data and didn’t include data
that consumers needed.
 We wanted to collect some meta-information about our
endpoints. For example, we wanted to identify the OAuth
scopes required for each endpoint. We wanted also: to be
smarter about how our resources were paginated; to assure
type-safety for user-supplied parameters; to generate
documentation from our code; to generate clients instead of
manually supplying patches to our Octokit suite.
To change our API, we focused on solving two problems:
Our GitHub API was entirely refactored to leverage GraphQL

 You let the client decide which data it needs to download.
(This type of design makes it possible to use clients where
smaller payload sizes are essential. For example, you have
an entity that describes an offer visualised on a number of
screens. Depending on a business need, you sometimes
need to send just a general section, sometimes a detailed
pitch. A mobile app based on GraphQL could simplify its
requests by only asking for the data it needs.)
 An insight into the required scopes could ensure that only the
appropriate types are being requested.
 You can batch requests, where you define dependencies
between two separate queries and fetch data efficiently.
 You can create subscriptions, where your client can receive
new data when it becomes available.
 You can defer data, where you choose to mark a part of your
response as time-insensitive.
What problems does GraphQL solve? What opportunities it
provides to integrators?

 The move to GraphQL marks a larger shift in our platform
strategy to be more transparent and more flexible.
 Since our application engineers are using the same GraphQL
platform that we’re making available to our integrators, this
provides us with the opportunity to ship UI features in
conjunction with API access.
 GraphQL represents a massive leap forward for API
development. Type safety, introspection, generated
documentation, and predictable responses benefit both the
maintainers and consumers of our platform.
What future opportunities it brings for us?

GraphQL Core Concepts
Queries A GraphQL query is used to fetch data.
Mutation Mutations are used to create/update/delete records.
Subscriptions
Clients can subscribe to an event and this creates a connection
between client and server. When that event occurs, the server
pushes the data to clients.

GraphQL allows to naturally query nested information.
Queries
{
allPersons {
name
age
posts {
title
}
}
}
{
"data": {
"allPersons": [
{
"name": "Johnny",
"age": 23,
"posts": [
{ "title": "GraphQL is awesome" },
{ "title": "Relay is a powerful GraphQL Client" }
]
},
...
]
}
}

Queries with arguments.
Queries
{
allPersons(last: 2) {
name
}
}
{
"data": {
"allPersons": [
{
"name": "Sarah"
},
{
"name": "Alice"
}
]
}
}

 Creating new data
 Updating existing data
 Deleting existing data
Mutation
mutation {
createPerson(name: "Bob", age: 36) {
name
age
}
}
{
"data": {
"createPerson": {
"name": "Bob",
"age": 36
}
}
}

 When a client subscribes to an event, it will initiate and hold a
steady connection to the server. Whenever that particular
event actually happens, the server pushes the corresponding
data to the client.
 Then, whenever a new mutation is performed that creates a
new Person, the server sends the information about this
person over to the client.
Subscriptions
subscription {
newPerson {
name
age
}
}
{
"newPerson": {
"name": "Bob",
"age": 36
}
}

GraphQL pros
 The server implements resolvers that fulfil specific graph
queries. The resolvers can function like „API gateways”
(caching, authentication, autorisation, etc.)
 One of the coolest side effects of using GraphQL is the ability
communicate gateways and services through any protocol
(http, http2, grpc, queues).
 The server returns only what the client asked for (no more, no
less; no wasted bits over the wire).
 The APIs sitting behind GraphQL do not need to worry about
serving every possible shape clients will want.
 The GraphQL layer can specifically optimise queries over the
RESTful APIs, minimizing API calls necessary to resolve a
query. Yes, you need to put in the work to implement each
resolver, but the explicitness is so liberating.
 GraphQL can be used in between the UI and API layers as
insulation, reducing concerns on both sides. GraphQL helps
both the UI and API layers as a result (facade of
microservices).

GraphQL cons
 It takes a notable calendar time to design the schema
thoughtfully such that it will have backwards compatibility as it
grows over time.
 There’s no caching because even if the client downloads
data, the operation is POST.
 If you change your service, you change your gateway.
 There is no versioning and the schema must be additive only
(or with backwards compatible implementation detail
changes).
 Breaking changes are possible, but you must phase it: add
new schema, roll out compensating changes to ALL clients,
remove old schema.
 Features like paging, filtering, and sorting are not built in and
require you to invest in defining your patterns and reusable
types.
 It works best when there is a single GraphQL server fulfilling
the whole schema. That requires a single service that multiple
teams can contribute resolvers to.
 GraphQL, along with other strongly-typed modeling systems,
doesn’t handle dynamic data very well. Concur supports
“Custom Fields”.

GraphQL is not OData
Jesse Ezell mentioned that some of the misconceptions about GraphQL come simply from GraphQL’s
name. Developers who have worked with SQL and OData hear “query language” and think “SQL.” As
Nick Schrock, co-creator of GraphQL, replied:

Differences Between GraphQL and Odata
Capabilities Use Case
Backends for
Frontends
Facade for
microservices
Single endpoint for
Web/Mobile UIs
GraphQL
Open Analytics
Hybrid Data Pipeline
Serving as a data
access layer
OData

Many use cases don’t require a wide variety of types, so limiting the types supported keeps things simple…
Until you're forced to jump through hoops to support a non-native type.
Data types
GraphQL OData
String, Int, Float, Boolean, and custom
 Lacks Decimal (Currency as Float/String)
 Lacks Date/Timestamp
33 Simple Types Defined
Supports complex types Supports complex types
Strong data typing Weak data typing

Allows generic applications to be written by allowing them to:
 Discover Data Available (Catalog Metadata)
 Discover Capabilities and Expected Behavior
Metadata
GraphQL OData
Introspection provides rich catalog metadata
 Nested data requires iterative introspection
Rich catalog metadata API
 Everything returned in a single call
Introspection provides insight into query capabilities,
but naming convention and behaviors are not defined.
Rich capability reporting with clearly defined behaviors.

Schemas evolve rapidly in our world of agile development.
Our tools must allow for this evolution to occur while avoiding breaking changes from deprecating fields.
Versioning / Schema Evolution
GraphQL OData
Apps/Clients must request the exact data they want
 Easy to identify who’s using what (or what’s not getting used)
 Promotes efficient code
@Deprecated annotation with comments returned via
introspection. Deprecated fields can still be requested, thus
avoiding breaking changes.
Versioning available, but discouraged.
Well defined protocol and model versioning within
the OData spec.

Most APIs require the ability to page data to avoid returning millions of rows of data.
Most applications only have a need of displaying a subset of data at a given time.
Pagination
GraphQL OData
There are a number of ways we could do pagination:
 Using (first:2 offset:2) to ask for the next two in the list.
 Using (first:2 after:$friendId), to ask for the next two after the
last friend we fetched.
 Using (first:2 after:$friendCursor), where we get a cursor from
the last item and use that to paginate.
Consistent behavior that is either client or server driven:
 Next links with maxpagesize setting as well as $top and $skip.

Other/advanced features
Feature GraphQL OData
Response Caching 3rd Party GraphQL centric(GraphQL Client),
Build Your Own
HTTP, 3rd Party OData centric, Build Your Own
Transactions No (“not needed”) Yes – “Change Sets”
Delta Response (CDC) No Yes
Subscriptions / Callbacks Yes – Subscriptions Yes – Callbacks
Writing Data Yes – Called “Mutations” Mutations can return
data modified. All mutations utilize POST.
Yes - HTTP POST, PUT, PATCH or DELETE
operations utilized with data included in the payload.
Primary Keys Single “ID” Field Very Flexible (Composite Keys)
Data Formats JSON JSON, XML

Community
Feature GraphQL OData
Open Source Community Yes Yes
Server Libraries .NET, Clojure, Elixir, Erlang, Go, Groovy, Java,
JavaScript, PHP, Python, Scala, Ruby
.NET, Java, JavaScript, Python
Client Libraries .NET, C++, Java, JavaScript, Python, Tcl/Tk .NET, Go, Java, JavaScript, Python,
Swift/Objective-C
http://graphql.org/code/ http://www.odata.org/libraries/

“
Objectivity Ltd. is an international IT company with British roots. We have
been guiding our clients through digital transformation since 1991. We are
here to help organisations create a genuine business advantage that
leverages the newest technologies and innovative thinking.
For the last four years running we have been awarded the prestigious
“Great Place to Work” award. We were runners-up in 2015, 2016 and
2018, while in 2017 we took the gold medal! This proves that we attract the
best of the best in order to maximise the value we bring to end users.
At Objectivity, we do more than just developing software. We help our
clients solve their business challenges through digital transformation. We
deliver a wide range of digital transformation solutions: web and desktop
applications IoT, RPA, Big Data, Machine Learning, proactive maintenance
and support.
We design solutions in close cooperation with our clients. To meet their
needs and expectations, dedicated teams and tribes are formed. They are
tightly aligned to the Client’s business.
We’re a team of over 600 people that continues to grow. The people who
make up Objectivity love their work, and we never miss an opportunity to
share knowledge and experience. Best of all, we even have fun doing it.
We are a values-driven organisation. We achieve our goals thanks to five
key values deeply rooted in our company DNA: Win-Win, People, Integrity,
Excellence, Agility.
This material has been prepared for general informational purposes only.
Please refer to your advisors for specific advice.
The views of third parties set out in this publication are not necessarily the
views of the organization. Moreover, they should be seen in the context of
the time they were made.
www.objectivity.co.uk
Copyright © Objectivity Bespoke Software Specialists Sp. z o.o. 2019
or
Copyright © Objectivity IT Solutions Sp. z o.o. 2019
Yaroslav Gontar
Technical Architect at Objectivity

GraphQL research summary

More Related Content

What's hot (17)

Similar to GraphQL research summary (20)

Recently uploaded (20)

GraphQL research summary