Introduction on GraphQL

GraphQL is a query language and runtime system. Clients form requests (called queries and mutations) by using the GraphQL query language, and the GraphQL server executes these requests and returns the data in a response. Unlike REST APIs, which expose a different endpoint for each resource object, a GraphQL API makes all data available at a single endpoint. A client specifies exactly what data they want, and the server responds with only that data. GraphQL is seen as a modern alternative to a REST-based architecture and aims to solve its shortcomings.

alt text

Documentation

The documentation for a GraphQL API lives side-by-side with the code that constitutes it. Combined with the typed Schema, this means that we can generate accurate and up-to-date documentation whenever something changes. Using GraphQL's introspection feature, it's possible to query the Schema itself to explore its contents and documentation.

Deprecation is a first-class citizen. We can easily mark a part of our Schema as deprecated, and this will also be reflected in the documentation. GraphQL tooling, such as client libraries, is also expected to communicate to the developer that a deprecated tool is being used.

GraphQL Basics

Everything that's available through a GraphQL API is typed and included in its schema. The schema can be used to build queries that only return the data that's needed. This solves the problem of over-fetching data. It also makes it easier to know which fields each app is using, which helps with improving an API over time. Find the entire schema in the side-menu or view a visual representation of the schema using Chargetrip Voyager.

Having a schema before querying helps validate a query before executing it. This eliminates unwelcome surprises like unavailable data or erroneous structures.

All GraphQL requests are sent to the same endpoint, which means that it is often possible to retrieve all the necessary data in a single request. Using GraphQL features such as connections, variables, and aliases, can make the queries incredibly efficient and retrieve data about many resource types in a single request. Learn more about query features here.

Primary operations

GraphQL has three primary operations: Queries, Mutations, and Subscriptions. Below are examples of each one.

          query {  carList {    id    carModel  }}