In this chapter, you will be referencing the use of an Express.js GraphQL server to assist you with learning about GraphQL. You will find this file in this chapter’s GitHub repository at https://github.com/PacktPublishing/Digital-Transformation-and-Modernization-with-IBM-API-Connect/tree/main/Chapter09.
You should copy the tar file from there to your local environment. You will be utilizing the API Manager to perform the development tasks in this chapter, which may require you to download additional software from the web to install the Express components. In addition, you may need to update your /etc/hosts file to reach the downloaded GraphQL Express web server implementation. For example, you can add a line similar to 192.168.168.205 mygraphql.com to /etc/hosts that identifies the IP address and hostname of your GraphQL server implementation.
Now, it’s time to learn more about GraphQL and the motivation to utilize it in certain circumstances.
Why GraphQL?
Before you learn about the benefits of GraphQL, you might be wondering, what is GraphQL? GraphQL is a query language but not for querying databases. It’s a query language for APIs, but in many cases, it may eventually interface with databases. From an API consumer’s perspective, it’s a query language for the client to specify which data fields it needs.
The motivation for the consumer to use GraphQL surrounds collecting payload data that’s returned from APIs. In some cases, you receive more data than what is necessary and that impacts bandwidth. In other cases, you don’t get enough data and need to create additional APIs to fetch additional data. Those two cases are referred to as over-fetching and under-fetching. Let’s understand each of them:
- Over-fetching happens when an API returns data elements you do not need nor want. This extraneous information can be just ignored but has a cost, especially if there are lots of additional fields. It’s a waste and affects latency.
- Under-fetching is observed when the endpoint returns too little data and requires an API’s client to execute another endpoint (API) to capture the information it needs to interact with the user. Another situation where under-fetching is apparent is when you require a list of elements. For example, you may only want to display 10 elements but there are many more elements you may require if the user doesn’t see the element in the first 10. In a traditional API method, you would make another API request to fetch additional elements that are required. When this scenario is present in your APIs, this is referred to as the {n + 1} request problem.
- Although not generally included in discussions on over-fetching and under-fetching, another implementation that exacerbates the data access problem is what we call replication fetching. This is when you implement similar APIs to support business partners in a B2B situation by replicating the implementation but removing data elements to support the business agreement. This leads to multiple versions and more complex modifications because of the existence of multiple copies.
In all such cases, they are potential performance bottlenecks and worse yet, a versioning nightmare. If you can specify how you want to receive your data, wouldn’t you prefer it in a single API? That is the value of GraphQL. Does that mean that REST is going away? No. GraphQL is just an alternative for data-intensive services where the client specifies the required elements.
How someone builds your GraphQL server will require you to learn about a few tenants of GraphQL.
Information
To learn more about the basics of GraphQL, visit https://graphql.org/.
Although you will not be learning how to build a GraphQL server from the ground up, it will be beneficial to understand the basics. You will learn about those next.
GraphQL anatomy
Solving the aforementioned fetching problems with GraphQL can help you with your API. However, GraphQL provides more capabilities that are additional benefits. You should be familiar with the following three things:
- Types
- Queries
- Resolvers
You will be introduced to each of these so that you can develop a basic understanding of what the designers of the GraphQL server are doing.
Types
When you build out GraphQL, you will observe that it is strongly typed. As you build your schema, you define various data types that will be used in the GraphQL application. When you create a schema, the syntax you use is based on the Schema Definition Language (SDL). In SDL, you have various types to utilize. Among them are scalar types of String, Int, Floats, Booleans, and ID. You should be aware that every type is nullable. The exception is if the field uses an exclamation point (!) to specify that the field must contain a value. A field that is not nullable is defined as follows:
id: ID!
As an example, if you wanted to build a schema based on an FHIR resource, you could create a schema based on the FHIR specification, as follows:

Figure 9.1 – FHIR specification for Address
Using the FHIR specification, you could build a schema that supports the following example:
“address”: [ {
“use”: “home”,
“type”: “physical”,
“line”: [ “2125 Triple House Lane”],
“city”: “Arcola”,
“district”: “Arcola”,
“state”: “Missouri”,
“postalCode”: “65603”
The FHIR specification would then guide you to build a schema that follows this:
type AddressSchema {
use: addressEnumType
type: addressTypeEnum
text: String
line: String
city: String
district: String
state: String
postalCode: String
country: String
}
This is just an example of part of the schema. With GraphQL, you will be wrapping this definition into the Query type. The hierarchy would be a Patient schema that has an address that references AddressSchema:
type Patient {
resourceType: String
id: ID!
active: Boolean
name: [NameSchema]
gender: String
address: [AddressSchema]
}
All of these structures are referenced in the Query type, which is what the API will be using to specify the elements it requires. The Query schema is defined as follows:
type Query {
patient: [Patient]
patientById(id: ID!): Patient
}
At this point, you probably have an understanding of how schemas are created. You have seen how the Query type references the Patient type, which contains the AddressSchema type. You will now learn more about queries, mutations, and how data is accessed using resolvers.