Blog
September 22, 2020
GraphQL for REST APIs is getting more and more attention these days. But what is GraphQL? And why should you go from REST to GraphQL?
Find out in this blog.
What Is GraphQL?
GraphQL is a query language designed to make accessing one or more REST APIs easier and more flexible. That's because it lets you ask for what you want in a single query. As a result, some are considering migrating their architecture from REST to GraphQL.
GraphQL is the one of the most recent advancements in API technology. Past technological advancements took us from SOAP to REST APIs. And before that, took us from legacy applications like mainframe programs to SOAP APIs.
Back to topExtending REST to GraphQL: An Example
REST APIs do have drawbacks, which is why many some organizations are extending REST to GraphQL.
Let’s look at one simple example just to highlight where this is all going. Suppose an application developer has two REST APIs. One retrieves a rather extensive list of information (discrete items of data) on a specific customer. It might look something like this (assume a customer id of 38):
Request: https://endpoint01.8080/Customers/38
Response: {
"lastName":"Smith",
"firstName":"Jack",
"streetAddress":"123 East Main St",
"city":"Syracuse",
"dateOfBirth":"1987-09-12",
...
}
A second API retrieves and array of orders for a given customer (also containing many data items):
Request: https://endpoint02:1840/Customers/38/Orders
Response: {
“Orders”: [
{
“orderId”:”ORD#01r50”,
“orderDate”:”2020-01-23”,
“orderTotal”:352.00,
“shippingMethod”:”USPS”,
...
},
{
“orderId”:”ODH10lk2”,
“orderDate”:”2020-01-23”,
…
}
]
}
Now suppose that the developer only needs the customer name and address along with a list of the order id and order total for orders placed on a specific date. They would need to make two calls and then parse through the results for the information they require.
Not so horrible — but what if there are more than two APIs involved? Or the application feature will be used often? Or it must be iterated for many customers? It can become a bit “chatty,” wasting bandwidth and placing more burden on the developer.
This is where GraphQL comes in:
POST /CustomerOrders/graphqlendpoint? HTTP/1.1
query {
Customers (id: “38”) {
lastName
firstName
streetAddress
city
state
Orders (orderDate: “2020-08-21”) {
orderId
orderTotal
}
}
}
Using this query, the developer can make just one call to a GraphQL endpoint and return only the data that is needed. Using a variety of GraphQL schema definitions, the GraphQL engine can interpret this query, execute the appropriate REST APIs, and marshal the results into a single response. Furthermore, if the functionality of the application expands and later needs some additional information it can simply be added to the existing query.
You can see that once a developer becomes skilled with GraphQL, this will be a much easier way to interact with one, or multiple, related APIs. Some API platforms support GraphQL, whereas others do not. Akana API management recently announced full support for GraphQL APIs – allowing your team to conduct complex data-first API management strategies.
Back to topThe Complete Lifecycle
Whether you're using GraphQL or not, it's important to manage the complete API lifecycle and become an expert in API basics. Explore our content hubs and become an expert today.
GraphQL Advantage: Retrieving Data Faster
GraphQL does for REST APIs what SQL did for flat files: retrieved data faster.
Here's why.
If, like me, you are or were a mainframe programmer, you are probably familiar with a rather old file system called VSAM (Virtual Storage Access Method). This was an architecture that consisted of flat files. Analogous to my REST example above you might have a customer file and an order file.
Programmers needing to obtain information on a specific customer and their orders would need to read through, using separate reads, each of these files to obtain the data they need. Each read would return an entire record from the file regardless of the specific needs of the application. If you think of each JSON document returned by the REST APIs described above as a single row of data from a flat file, then you see the analogy here.
Now along comes database architecture and, more pertinent to this topic, Structured Query Language (SQL). SQL allowed developers to execute a single query that could return related information from one or more underlying files. In addition, it would only return the data elements that were required. It quickly became the preferred way of retrieving/updating application data and has remained so for decades.
As standards and techniques evolve and mature, I think the advantages that GraphQL brings to the application developer will help to crystalize GraphQL into an industry standard. It can technically be extended to other data access architectures. Imagine the ability to write a single query that could organize and deliver data from a wide variety of resources such as REST and SOAP APIs as well as raw data from ... you pick the data store!
The sky is the limit.
Back to topGraphQL Limitations
There are some limitations to GraphQL. For example, it needs to take on some of the burdens formerly handled by individual applications. Beyond the obvious need to handling the marshaling and orchestration between a single GraphQL query and multiple REST API invocations, a GraphQL endpoint will need to protect itself from the effects of malicious and ill-formed queries.
Drawing of my database analogy, you may have heard of a Cartesian Product. This is a poorly formed SQL query that can bring an entire database subsystem to its knees. Any implementation of GraphQL will need to consider similar issues.
How do you prevent ill-formed GraphQL queries from tying up an entire endpoint? DB2 employed a technique known as a BIND. A BIND generates an “Access Path” to your data that can be analyzed for efficiency. This is possible since the database environment is completely contained and controlled. That will not be the case with APIs as the actual processes that sit behind them are unknown.
So how can GraphQL manage this? The answer is probably evolving but for now it comes down to a combination of techniques such as throttling and rate limiting.
Back to topMaximize GraphQL and REST APIs
To get the most out of GraphQL and REST APIs, you need the right API platform — like Akana.
Akana makes it easy to manage your REST APIs through the full lifecycle. With Akana, you get:
- Akana API lifecycle management tools
- Akana developer portal
- Akana API gateway
- Akana API analytics tools
Plus, Akana also has Sola, which integrates seamlessly to help you manage your mainframe APIs.
See for yourself how Akana and Sola make it easy to maximize GraphQL and REST APIs.