Will take over GraphQL REST

GraphQL - API for your interface

The interface is everything

Interfaces are sometimes one of the most important aspects in the development of software systems. Classically, data from one service is exposed to another via a REST interface. In a recently published article we looked at how to implement an interface with gRPC. GRPC relies on the variant of one Remote procedure call whereby the interface was predefined with Protobuf and thus typified function calls on target systems possible. This has certain advantages over a REST interface, since the interface was declared explicitly and the way in which a function call is made is relatively faster.

If not REST or gRPC, then GraphQL!

There is another way in which one can alternatively expose data from a service; namely as a search query, to English as Query Language. The idea here is that the search query, or also Query called, behaves identically to a query to a database or to a search engine such as Apache Solr. The search query only contains the search terms that are required for the respective case. One of the prerequisites for the target system is that it already knows and provides all possible search terms. This is exactly what GraphQL does - the query language for your future searchable API.

How do you please again?

GraphQL describes the structure of the interface in the following steps:

  1. Describe your data

    Here is a data type Project with 3 entries, the latter an array of type User. The entirety of all defined data types is called a schema and is explained again later.

  2. Look for what you want

    It's a query. It looks for the tagline within the type project with the unique name “GraphQL”.

  3. Get understandable search results

    The search result is structured exactly like Query and contains an existing tagline.

This is the simplest and fastest description of how a GraphQL interface should behave.

Advantages of a GraphQL interface

So, software systems require data exchange between the individual system components. Service A gets certain data from Service B. Often not all data exposed by Service B is actually needed in the business logic. This means that the preparation and exposure of ready-made data structures - as is typically the case with a REST interface - is not always efficient. Sure, you can give the REST endpoint a certain number of parameters in order to get the desired result, but you are very limited and inflexible.

GraphQL offers an intermediate step in the form of a GraphQL server that aggregates all data sources and makes them available to the client.

Typed graph with the GraphQL schema

The main part of a GraphQL implementation is the GraphQL schema, from here on simply called the schema. The schema is the domain definition of all fields connected in the graph. With every GraphQL interface there is a scheme that defines in advance what is available and thus determines what you can search for.

For example, the scheme for a blog post interface can look like this:

We can already see that there are different type definitions:

  • Query
    The denotes a callable, ready-made query. In this case you can display all blog posts with or a single blog post with, whereby you can give the unique identifier with an id parameter.

    Note: the bang means that this value must be present.

  • mutation
    The denotes a callable, ready-made function that can modify values ​​in the interface. In the example, you can create a new blog post via. The parameter title, the content and the unique author identifier must be given.

  • object
    An object is any structured type within the graph. In the example above with the blog interface, an object with the fields id, title, content and hasAuthor and a second object with the fields id, name and hasBlog Are defined. You can do this without a pre-made one Query-Parsing and evaluating the function.

  • Scalar
    A scalar type is any field within a structured object. In this case is and can, for example, be a scalar field with a type which must not be zero. A scalar field can also be an array of individual scalar values.

    Note: The basic types are for GraphQL (32-bit), (UTF-8),,, and die (serialized like string).

For the sake of completeness, it should be noted that there are other types. Belong among them Enums, Lists, union, Interfaces, un Input types. You can look them up in the official documentation for the scheme and types.

Underfetching and overfetching

A second important advantage of GraphQL is the adequate resolution of the actually required data. It will not too much, called Overfetching, But also not too little, called Underfetching, delivered. Thus, the interface is efficient and, if implemented correctly, always better performing.

  • Underfetching is when not all data are delivered in a response. Often not all resources are output and only references to other resources are given, which requires further requests.

    A REST API can, for example, provide CMS data. When calling the API endpoint, the BlogPosts would not return all the desired values, but references that would require further REST calls as a response.

  • Overfetching is when more than the desired data is supplied in a response. This is the exact opposite of underfetching. This means that when a REST API is called, there are too many values ​​in the response than desired and thus the interface would not be as efficient.

A quick word about caching

Of course, the question quickly arises whether GraphQL can also take over the caching of queries. The GraphQL server, which aggregates the data records, does not save them. Therefore, client-side caching or even server-side caching must be implemented and taken into account separately.

Test a few queries with GraphiQL

GraphiQL is the official reference implementation of a GraphQL IDE. You can use it to write, test and analyze queries. The IDE can thus be made available for your own interface in order to offer a graphical surface.

As you can see very nicely above, there is also a live demo of it, with which you can very well take the first steps with GraphQL. With GraphiQL all possible queries can be tested and the schema can also be displayed in full. The scheme can be viewed in the window on the right. It looks something like this:

For the sake of experimentation, I wrote the following query, which should give the result for the species with its name, its identifier, its designation and its language.

The query, if executed correctly, delivers the following rather funny result:

The species with name “”, identifier ““, designation ““ and language ““ is the result self-explanatory. You always get exactly the data that you initially want to get via the query, no more and no less.

GraphQL is just a specification

You still have to implement GraphQL yourself. Fortunately, there are already established libraries that you can use, but basically you still have to write the interface yourself.

The white paper of the specification is available on the official website and contains the complete definition of what a full-fledged GraphQL implementation must have. The first paragraph of the introduction reads as follows:

"GraphQL is a query language designed to build client applications by providing an intuitive and flexible syntax and system for describing their data requirements and interactions."

Implementation of a GraphQL interface

Write query resolvers

A resolver is a piece of code that resolves the values ​​for a GraphQL object. In Java, a resolver is a Java class that inherits from a GraphQL resolver class and the desired objects via the data connections (Connectors) assemble.

The schema definition

Let's take a scheme that is supposed to expose blog posts via a GraphQL interface. The scheme would include a BlogPost object with at least a title and a field for the content. We want to get all blog posts aggregated via a query. It could look something like this:

So, we have the GraphQL schema and thus the domain definition. Now we want to provide our Java-based GraphQL server with resolvers in order to aggregate all of this data. First we need to recreate the BlogPost object in Java. The best we can do is make a POJO class with the same name and fields:

Now we have to build an aggregation class which all BlogPosts provides. This class is necessary because we will not use a database connection for the example and only provide the data as an example. Let's call the BlogPostRepository. It manages all BlogPosts and can output them using a corresponding method and adds new BlogPosts using a method.

Now we have our data, so to speak, and its connection mocked. The next step is the resolver for the BlogPosts. This implements GraphQLRootResolver () here and bears the class name of the BlogPostResolver object to be resolved. This class implements our query.

Now we can integrate this resolver in our interface. For this we build a servlet that implements the class. The desired endpoint is. We have to create an object of the type which is via the Scheme-File, as well as the corresponding Resolvers, here who knows. It looks like this:

Connect datasources

Usually you want to connect several data sources, so-called data sources. To do this, you have to write a corresponding connector for each data source. The connector then transfers the necessary values ​​to the respective resolver. The values ​​are already known in advance via the domain definition of the GraphQL interface schema.

Finished implementations and tools

GraphQL was originally developed by Facebook. The story of its origins can be admired in an informative 30-minute documentary film. The bottom line is that due to the complex requirements of the well-known Facebook wall, a more flexible and efficient interface to the actual data was required and a solution, now known as GraphQL, was worked on internally. In 2015 the implementation was made open source and the further development was shifted to a separate GraphQL Foundation. As for the Cloud Native Foundation, there is also a landscape for the GraphQL Foundation.

Since GraphQL is actually just a white paper, a specification, there are numerous implementations. Over time, certain libraries and implementations have proven themselves. Here is a small list of the ecosystem around GraphQL:

GraphQL ecosystem

There is a lot more to write about GraphQL, but here we have explained the basics of how to use GraphQL and how to use it to design the appropriate interface for your next project.

Stay tuned!

Further links and resources

So what's this GraphQL thing I keep hearing about? | freeCodeCamp

GraphQL concepts I wish someone explained to me a year ago | Naresh Bhatia @ Medium

GraphQL Explained in 100 Seconds | Fireship

Building Modern APIs with GraphQL | AWS Summit 2019

GraphQL: The Documentary | Honeypot