Overview

I have been practicing GraphQL, so I am summarizing what I researched.

There is a helpful tutorial available, making it easy to get started. cf. www.howtographql.com

What is GraphQL

A query language for Web API development developed by Meta.

GraphQL is managed by the GraphQL Foundation, of which Meta is a member.

The specifications of GraphQL and all related projects are open source.

Features

• Used over HTTP
• Retrieves data by sending queries as POST requests
• Can fetch multiple data with a single endpoint
• GraphQL schemas and queries are designed based on the concept of directed graphs
• Schema-first
• Documentation
  • Being schema-first, the specifications are self-evident
  • Documentation can also be generated using document generators
• Type Definitions
  • Includes scalar types, object types, enum types, list types, non-null types, union types, input types, and interfaces
    • Input types are object types used as arguments for Queries and Mutations
    • Default is Nullable
      • maku.blog - Guidelines for Nullable and Non-null
• Flexibility in Data Retrieval
  • Can retrieve only the necessary data through Queries
  • Avoids over-fetching and under-fetching
• Version Management
  • Can manage versions
  • Can develop in a versionless manner by adding new types and fields
  • Generally avoids versioning
• Error Handling
  • Typically returns status code 200 even in case of errors, embedding error messages

Terminology

Only a few selected terms are listed.

Schema

Type definitions for queries.

type Query {
  user: User
}

Query

A query for data retrieval.

query {
  user {
	name
  }
}

Mutation

A query for data updates.

mutation {
  updateUser {
	name
  }
}

Subscription

A query to monitor data changes.

subscription {
  user {
	name
  }
}

Argument

Arguments passed to a query.

{
  user(id: 123) {
    username
    email
  }
}

Related Technologies

GraphQL Mesh

A gateway server (GraphQL Gateway) for APIs implemented with specifications like gRPC, OpenAPI, Swagger, oData, SOAP, GraphQL, etc.

As long as there is an API specification, you can access the API with GraphQL queries.

cf. the-guild.dev

openapi-to-graphql

Converts API specifications based on OpenAPI to GraphQL Schema.

cf. github.com - IBM/openapi-to-graphql

graphql-tools

A handy tool for creating GraphQL Schemas. Can also create mocks.

cf. github.com - ardatan/graphql-tools

GraphQL Gateway

Performance

• N+1
  • Data Loader
    • Consolidates multiple SELECTs on the same table into a single SELECT
    • Features Batch and Cache
      • cf. lyohe.github.io - Key Features
• As queries become complex, the request body can become bloated
  • Persisted Query
    • A feature provided by Apollo, a GraphQL tool
    • Prepares an ID corresponding to the query, exchanging the ID and query to reduce request parameters
      • By making the endpoint for exchange a GET, it can be cached
• Since it is a POST request, HTTP caching cannot be used
  • Persisted Query

Impressions

Compared to Restful APIs, it might take a bit more effort to get started, but the benefits seem significant.

There seem to be various types of GraphQL clients, which might make selection challenging.

cf. user-first.ikyu.co.jp - Apollo Client May Not Be Necessary for Your Product

References

• graphql.org
• zenn.dev - Comprehensive Articles on GraphQL
• kinsta.com - Comparison of GraphQL and REST: Key Differences to Know
• panda-program.com - Learned GraphQL Overview from "First GraphQL"
• qiita.com - GraphQL Schema and Type Definitions
• gist.github.com - Things to Know About GraphQL
• maku.blog - GraphQL Best Practices
• qiita.com - Various Performance Issues in GraphQL
• engineering.mercari.com - Considerations When Introducing GraphQL
• engineering.mercari.com - Implementing GraphQL Server with NestJS in Mercari Shops
• lyohe.github.io - Reading graphql/dataloader
• zenn.dev - Four Approaches to Solve N+1 Problems in GraphQL
• www.apollographql.com - GraphQL Concepts Visualized