GraphQL provides a new philosophy for building APIs, which helps us to structure the interaction between frontend and backend. To structure the interaction, GraphQL offers two languages: a declarative, typed query language for APIs and a schema language. These two languages have different purposes.

The query language allows the frontend to interact with the backend. It provides primitives for retrieving data, writing data and getting notified when data changes.

GraphQL schema language allows us to define and describe our data structures in the form of a schema.


Picture by kstudio / Freepik

The GraphQL schema can be compared to a à-la-carte menu in a restaurant, showing all the delicious dishes that clients may choose from. The menu has been defined by the owner of the restaurant, and it serves as an interface to the backend of the restaurant (a.k.a. kitchen). Ordering dishes that are not on the menu is not possible, simply because the kitchen is not prepared for it. The same is true for GraphQL: the GraphQL schema is the interface between frontend and backend, and the schema defines the data structure that is available on the backend

In this analogy, a GraphQL query is comparable to the order a client places in the restaurant. In this order, the client may select certain dishes from the menu, such as a starter and main dish. The same is true in GraphQL: in a GraphQL query, we refer to the elements that have been defined in the GraphQL schema.

Want to learn more about GraphQL? Check out the book GraphQL API Design and learn how to use GraphQL to use both the query and the schema language to build APIs.

Why are there Two Languages in GraphQL?

Also published on Medium.

Tagged on:

Matthias Biehl

As API strategist, Matthias helps clients discover their opportunities for innovation with APIs & ecosystems and turn them into actionable digital strategies. Based on his experience in leading large-scale API initiatives in both business and technology roles, he shares best practices and provides both strategic and practical guidance. He has stayed a techie at heart and at some point, got a Ph.D. Matthias publishes a blog at api-university.com, is the author of several books on APIs, and regularly speaks at technology conferences.