DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Generative AI has transformed nearly every industry. How can you leverage GenAI to improve your productivity and efficiency?

SBOMs are essential to circumventing software supply chain attacks, and they provide visibility into various software components.

Related

  • Using Slash GraphQL to Create InstaMeme—A Meme Sharing App
  • Doris vs Elasticsearch: A Comparison and Practical Cost Case Study
  • Finally, an ORM That Matches Modern Architectural Patterns!
  • Keep Calm and Column Wise

Trending

  • Spring Cloud LoadBalancer vs Netflix Ribbon
  • One Checkbox to Cloud: Migrating from Tosca DEX Agents to E2G
  • Spring and PersistenceContextType.EXTENDED
  • Beyond Java Streams: Exploring Alternative Functional Programming Approaches in Java
  1. DZone
  2. Data Engineering
  3. Databases
  4. Understanding the Rise of GraphQL: GraphQL vs. a JSON DSL

Understanding the Rise of GraphQL: GraphQL vs. a JSON DSL

Let's look at GraphQL and why it is a better choice than a JSON DSL. Do you agree? Let us know in the comments.

By 
Sandip Devarkonda user avatar
Sandip Devarkonda
·
Jul. 31, 18 · Opinion
Likes (7)
Comment
Save
Tweet
Share
12.6K Views

Join the DZone community and get the full member experience.

Join For Free

It turns out that GraphQL is pretty awesome. I didn’t always see it that way. The first few times I ran across GraphQL, I was pretty skeptical of its touted benefits because the cost of putting together a GraphQL system seemed too high. It also seemed to me that all the benefits of GraphQL could still be achieved by just creating a custom JSON DSL (query language using JSON).

For example, a “read” query might look like this in GraphQL:

But if we were to use a custom JSON query language, we might have come up with this ourselves:

As you can see, the JSON DSL is “uglier” but it’s a lot more flexible, no additional tooling, and you can create your own “query language.”

Benefits of a JSON DSL:

  1. No change in tooling on the client
  2. JSON objects can be easily manipulated, especially in a language like Javascript where JSON can easily be parsed into a Javascript object.
  3. No change in tooling on the server

Directives and fragments in GraphQL would not even be required in JSON because you can just manipulate a POJO (plain old javascript object) exactly the way you need to.

The Problems With a JSON DSL

However, the JSON DSL approach has a few problems that start emerging when you deploy it over a long-running software project or a large team.

Problems on the Client-Side:

Where is the “grammar” of your JSON DSL? REST-ish endpoints propose a simple, if slightly ad-hoc, grammar with HTTP verbs and simple JSON being chucked back and forth. But in a custom JSON DSL what if the “query language” changes on the server side? How you do create a specification for the client to create queries in JSON that are valid?

With a REST-ish design, there’s no query language. The JSON that is sent back and forth adheres to a “shape” or a skeleton but not really a dynamic query language. For example, you “POST” an “object.” This allows the creation of things like a “swagger” spec. For example, a “swagger” specification of your API would look like this:

However, what is the “swagger” equivalent for a single HTTP endpoint that takes our JSON query? A query language follows a “grammar” and not really a “shape”.

On the Server-Side:

Serving a JSON DSL based API requires that you:

  1. Need to parse the incoming JSON query and
  2. Analyse the parsed query to perform type-checks
  3. Convert it to an internal form that you can break down and process (“resolving”)

This is suddenly turning from a fun

“oh-hey-i’ll-just-use-some-clever-if-else-statements-to-validate-the-JSON” into

“why-is-this-a-1000-line-conditional-block” or even worse

“who-will-ever-maintain-this-random-new-language-that-exists-only-in-the-mind-of-the-first-employee” situation.

Then, once you start off writing it in a naive way, you’ll soon realise that it’s easier to write a mini-compiler into your API server as a query parser + “resolver” that can actually understand the JSON DSL and process it in phases as opposed to dealing with the JSON DSL in an ad-hoc way.

Welcome to GraphQL

Once you go through the effort above, you’ll realize that you’ve invented a GraphQL. But it’s “uglier” (because there seems to be some key-value cruft), and there’s no standard spec.

GraphQL approaches the problem of being able to make queries against a server by enforcing a few key ideas.

Idea #1: A Standard “Grammar” for Querying

GraphQL defines a standard grammar for a query language to read/write data. It kind of looks like a neater JSON with just the keys and allows you to pass arbitrary parameters in the query.

Idea #2: Force the Server to Publish a Schema

The GraphQL spec mandates that a GraphQL server should publish a schema describing the types of the data and the “parameters” (arguments per GraphQL).

Image taken from graphql.org

When the server publishes a schema, suddenly a whole host of tools and plugins become possible which can start solving the problems that were fundamental to using APIs. In fact, this suddenly makes a GraphQL server + client system better even if you didn’t have to make “queries” and could have just gotten away with simple REST.

The API specification is a part of writing the source code!

Awesome Problem Solved #1: API Validation at Build Time

Whether you’re making “queries” or simple REST calls this idea of having a schema now allows you (or even better, the community ;)) to write tooling that can validate your API calls.

In fact, you can even add IDE tooling to do that validation as you write code!

ESLint configured with Atom to validate GraphQL queries

For typed language clients like Java (Android) or Swift (iOS), you can even generate the SDK code directly and nuke a large amount of boilerplate.

Awesome Problem Solved #2: Reduction in Async Client Code Boilerplate

Async API calls from the client can now be specified as declarative queries and the boilerplate that fetches the data and renders the UI can be neatly abstracted away. This allows you to write much cleaner UI code!

Check out a list of awesome react clients here.

Important note: GraphQL doesn’t itself solve these problems. It’s design choices allow the community to solve these problems.

GraphQL is Awesome

Yes, but even more so, the GraphQL community is awesome! Client-side tooling would have been a nightmare for a whole new query language, but amazing client-side tools are paving the way. Apollo’s react/react-native GraphQL client library even reduces the boilerplate required to use the results of the GraphQL query in your react component!

GraphQL servers are still a bit of a pain to write compared to writing simple REST-ish servers. A backend developer can’t think with URL paths and good old JSON and instead needs to deal with an abstract syntax tree and “resolvers” up front. Add authentication to the mix and the resolution logic becomes a little more complicated. Performance also gets harder to reason about because of the recursive nature of processing a GraphQL query. exAspArk talks about the (n+1) problem and approaches to solving it here.

But these really are teething problems in the ecosystem and the tide is turning with tools that offer ready-to-use GraphQL APIs like the Hasura GraphQL Engine, Postgraphile, etc. Better and better tooling and more discussions around different patterns will start emerging and making life easier for the backend developer!

Summary

GraphQL is an amazing leap forward for consuming APIs! GraphQL is a million times better than writing your own query language in JSON especially if you care about your colleagues and the longevity of your project. In fact, consuming GraphQL is far better than consuming REST because of the type-safety tooling that’s built into the GraphQL server and the client-side tooling. GraphQL servers are still a little hard to write, but it’s getting better day-by-day thanks to the tireless work of folks in the community!

JSON Domain-Specific Language GraphQL Database

Opinions expressed by DZone contributors are their own.

Related

  • Using Slash GraphQL to Create InstaMeme—A Meme Sharing App
  • Doris vs Elasticsearch: A Comparison and Practical Cost Case Study
  • Finally, an ORM That Matches Modern Architectural Patterns!
  • Keep Calm and Column Wise

Partner Resources

×

Comments

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • [email protected]

Let's be friends: