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:
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.
Look for what you want
It's a query. It looks for the tagline within the type project with the unique name “GraphQL”.
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:
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.
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.
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.
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:
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:
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.
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
- Makes me smarter in math
- What is Neuro Boost IQ
- How do you accept imperfection in writing
- Is acupressure or acupuncture a better choice
- What do you like about Boulder Colorado
- Who is the first billionaire in the world
- What a delusion you have
- Did Hitler ever leave Europe
- Why isn't Rose the picture of Blackpink
- Which is the best hotel in Vail
- Your ears are crossed
- Why does eating feces make you sick
- What is the state animal of Kerala
- When should I prepare for MIT?
- Can someone have calm panic attacks
- What is the deepest ocean trench in the world
- Which slot machines are losers at Foxwood
- Where can I find nightingales
- Why do some banks open on Sunday?
- Makes sugar as addicting as heroin
- What is wind and pressure in detail
- Would Buddha follow astrology
- Denmark has a nanny job
- How is a baby given an eye exam
- What is gender diversity
- How do I open a Z file
- What sets Lowes apart from Home Depot
- What is eating my ripe cherry tomatoes
- Where did Sahil Khattar disappear
- How long will Trump be in jail?
- What is the meaning of moksha
- What is the nickname of Komal
- What's wrong with the Chinese stock exchange
- How are religions so ignorant