GraphQL Schema Design Principles adopted by NEWT

🧩 NEWT Stack

Here is a quick summary of the NEWT stack for each platform:

Backend + Web: TypeScript

Web: React + Next.JS

iOS: Swift

Android: Kotlin

API Layer: GraphQL

If you want to learn more about each platform, check out the following blogs

Backend: https://engineering.reiwatravel.co.jp/blog/newt-backend-stack

Frontend: https://engineering.reiwatravel.co.jp/blog/newt-frontend-stack

iOS: https://engineering.reiwatravel.co.jp/blog/newt-ios-stack-2021

Android: https://engineering.reiwatravel.co.jp/blog/newt-android-architecture

🤔 Why GraphQL?

We compared some common options before selecting GraphQL. Here’s a summary of the criteria we considered:

Candidates

Criteria	REST	GraphQL	gRPC
Covers all platforms	✅	✅	⚠️
Scales with the organization (*)	✅	✅	✅
Self-documented	⚠️	✅	✅
Schema-based (consistency)	❌	✅	✅
Easy to learn	✅	⚠️	⚠️
Production development experience	✅	✅	❌

REST:

Simple to start but concerns over long-term endpoint maintainability.

GraphQL:

Met all our criteria. It has a slight learning curve, but maintaining a central schema is beneficial for future scaling.

gRPC:

Requires a proxy for web compatibility.

🔥 GraphQL Schema Design principles

The GraphQL principles we adopted at NEWT are:

One Graph

Demand-oriented schema design

🚪 1) One Graph

By having one graph, you maximize the value of GraphQL. The benefits include:

Single Endpoint: Access more data and services from a single query.

Central Data Catalog: A central catalog of all available data.

Portability Across Teams: Code, queries, skills, and experience are portable across teams.

Unified Access Control: Centralized management of the graph allows for unified access control policies.

How to scale One Graph?

Different ways to scale GraphQL include:

Apollo Federation

Schema Stitching

Schema Merging

Scaling GraphQL is primarily a backend implementation detail and does not affect clients since they continue to use a single entry point.

Ref:

Integrity Principles

Ensuring that the graph is well-defined, stable, and consistent

https://principledgraphql.com/integrity/#1-one-graph

🎯 2) Demand oriented schema design

Demand-oriented design means designing your schema around client-side use cases. The benefits include:

Benefits:

Simplified Schema

Reduce Over-fetching

Improved Developer Experience

Easier to Understand and Maintain

Reduce QA Costs

Key Points:

We apply three key points in this approach:

① Design schema around client-specific use cases

② Move business logic to the backend

③ Close collaboration with client-side engineers

① Design Schema around client-specific use cases

Do not reflect your database in your schema; use a client-first approach. This means having more specific, finer-grained mutations and queries. ❌ Database → Schema ✅ Client Use Cases → Schema

An explanation about Client Use cases schema:

Type User

Include only necessary fields used by clients.

created_at, updated_at, country_id are removed, since clients do not need them.

Use predictable values like Enum types.

Gender is not a string anymore; we use the Enum type.
Country returns a Country type.

Adapt fields around client use cases.

If the client side always needs to display the full name of customers, a combined fullName field is better than separate firstName and lastName fields.

Queries