GraphQL at High level

What is GraphQL?

A New API standard/specification that was invented & open-sourced by Facebook which describes the way that should behave a GraphQL server. It enables declarative data fetching by a single endpoint that responds from a query, instead of using multiple endpoints likes REST does.

A little bit of history about GraphQL

Actually, GraphQL is not anything new. Actually, worn as an internal solution at Facebook in Feb 2012, called “SuperGraph” by Nick Schrock (an initial member of the infrastructure team, a co-worker of Lee Byron) as a mobile solution to back and forth data efficiently between mobile and backends. The first prototype was created in a couple of days. Then Leen Byron, Nick, and Dan Schafer, starting to working very closely with the mobile team to support newsfeeds use cases, and after 3 weeks was the first initial version of GraphQL. Then, in August 2012, will launch one of the first version of GraphQL that support the mayor’s core features. Between August 2012 to January 2015, GraphQL is implemented in several features around Facebook, so at that moment born core concept and related open source project such as Fragments, Mutations, Subscriptions, Native Code Generation, Persistent Queries, Relay, Graphical. In January 2015, Facebook decide to get public GraphQL on ReactConference 2015. But in order to get something useful for the rest of the world, at that moment, GraphQL should be reevaluated, redesign the syntax and a lot of work to achieve a solid first specification with a rough implementation in Javascript on July 2015. Then the first production-ready version was on Sept 2016.

Imperative (REST) vs Declarative (GraphQL) data fetching approach

Imperative:

• Construct and send an HTTP request.
• receive and parse server response.
• store data locally.
• display data in the UI.

Declarative

• describes data requirements.
• display data in UI.

Three different common use case architecture of GraphQL

GraphQL server with a connected database

That basically works very well with the greenfield projects, so the flow of the information drives in a normal way. The client request information to the server, a Resolver address that request, then interacts with the database, and retrieve the information requested for the client. GraphQL is transport-layer and persistence structure agnostic, so GraphQL doesn’t care how the communication was performed (WebSocket, TCP, etc), or how was persisted (SQL, or Non-SQL data structure).

GraphQL layer that integrates existing systems

Another common use case of GraphQL when you have an entire existing system, it’s really complex to perform the communicate between APIs and to scale for new ones. So GraphQL acts as a facade of that complexity and allows us to hide that complexity.

GraphQL with connected database and integration of existing system

This approach is a hybrid between the first one and the second one. Your GraphQL server could be connected with a database, and also could be integrated with a legacy part of the system. So in that way, when the GraphQL server receives a request from the client, it could be answered from the connected database or some integrated APIs.

Now, that we have a very high-level idea GraphQL when is used, lets get started to see a little bit how GraphQL is conformed and structured:

The Schema Definition Language (SDL)

This is the core part of GraphQL. You should think in terms of data, not in the View when you are designing it. Also, another helpful tip would be, think Schemas like the contract between client/server fetching data structure. In a really simplified way, we could say that Schemas, is a collection of GraphQL types. Each Schema has its root types (Query, Mutation, Subscription, etc), that define the entry points.

Well, now will make a simple query example, that will declare in the entry point `Query`:

A simple example of a schema definition is the following:

As you see, If we want to make relationships between schemas, just declare it.

Well, let’s start to take a look in more detail the main parts of GraphQL and start to learn how to achieve this declarative data fetching approach:

Mutations

The mutations are the way that you change your data. There exist three different mutation:

• Creating new data
• updating existing data
• deleting existing data

Let’s take a look an example of mutation:

And the response of the server will be

In that way, we create and fetch information in a single round trip, maybe would be more useful to ask for ID, because it’s auto-generated from the backend side.

Subscription

In case we need real-time server information, the events are the common solutions (of course polling is the oldest way as well but it is not the case). In GraphQL, this mechanism is called Subscriptions.

When a client, subscribe to a particular event, called “NewPerson”. So each time that event happens, the server will send that particular data to the client.

Resolvers

Resolver is the mechanism of GraphQL to know how to get some particular “field” from the resource (It’s like an imperative part of GraphQL).

Fragments

A Fragment is a collection of fields on a specific type, which allows us to avoid the boilerplate data structure, it’s just to improve the structure and reusability of our data structure. Let's take a look at the following example:

GraphQL on Client-side

The idea to follow a declarative approach is to gain a lot of properties with less effort, instead of using an imperative approach. So exist, two mayors client-side implementation of GraphQL: Appollo Client and Relay. both of them perform the following task:

• directly sending queries and mutations without constructing an HTTP request
• view-layer integration integration & UI updates
• caching
• validating and optimizing queries based on the schema.

Well, let’s take a look closer about Objects and different data types on GraphQL:

Object & Scalar types

In GraphQL, there are two different kinds of types:

• Scalar Types: String , Int , Float , Boolean and ID .
• Object Types: have fields that express the properties of that type and are composable (for instance, User as we saw in the previous examples).

NOTE: In every GraphQL Schema, you can define your own scalar and object types.

Enums

For a set of fixed value, at language level support enums:

Interfaces

An interface, the same as other language support, allows us to define a contract that needs to be fulfilled. In terms of data structure, we can think of a common example where you need to support a common identifier for your Schemas. Let’s take a look at the following example:

Union Types

Union types help us to declare some field from one type or another.

So in that way when you are requesting for some field, for instance Person that could be an Adult or a Child .

So, when you are requesting information in that kind of data structure, you should use Conditional Fragments:

Thank you for reading it! let me know what do you think about it!

Please give me your thought about this short article, I love to share ideas, learn from others and I hope this article may be helpful for someone out there!

Also, you can be following me on Twitter, or contact me by Linkedin.