GraphQL API Schemas: Designing a better one


For basic UIs, expressing your application’s data needs in your GraphQL schema is simple. However, when your UI grows in size and complexity, it gets more challenging. Complex application user interfaces are well-known examples, such as the StackOverflow website or an Amazon product page.

We’ll go over some guidelines to bear in mind while creating your own GraphQL schema in this article.

This guide walks you through an easy-to-follow method for creating GraphQL schemas and modifying them as your application’s user interfaces get more sophisticated.

1. Use GraphQL for the right reasons 🤔

GraphQL is a great choice for organizations with multiple teams and systems that want to make their data easily available through a unified API.

Reasons to Use GraphQL:

2. Be specific when naming types

  • Why: It allows us to identify what types are relevant to other types and reduces naming collisions
  • Example: Prefer BusinessCategory instead of Category

3. Don’t over namespace fields

Why: Fields are already implicitly namespaced based on their type


  • ❌ Instead of:
  • ✅ Prefer:

4. Link via types, not IDs

If you are referring to one type from another, link directly to the type.

Why: Developers will be able to fetch data with greater flexibility this way. When you only provide the ID of the thing you’re linking to, the browser must make a follow-up request in order to retrieve data about it.


  • ❌ Instead of:
  • ✅ Prefer:

5. Use existing standardized types and scalars

Why: Using these types, we are able to model and consume common data types across the schema. It allows us to avoid duplication of effort and concepts.


  • ❌ Instead of:
  • ✅ Prefer:

6. Use triple quotes for descriptions

When adding descriptions to fields, use triple quotes ("""). Don't use #.

Why: GraphQL provides two ways to add comments quotes and hashtags :

  • """this is a description""" Descriptions should be used to describe fields and types.
  • # this is a comment The syntax is ignored by the parser and cannot be used for schematic documentation.


  • ❌ Instead of:
  • ✅ Prefer:

7. Spacing between field descriptions.

When adding multiple fields and descriptions, make sure they are spaced out!

Why: Easily readable!


  • ❌ Instead of:
  • ✅ Prefer:

8. Be as explicit as possible with your comments and descriptions

Why: The people who use the new schema you just wrote may not have the same knowledge as you. Try putting yourself in the shoes of a new employee you would want as much context as possible to understand what the schema represents so that you could make effective use of it

9. Use Interfaces For Abstraction

Interfaces are parental objects from which other objects can inherit.

Why: interface defines a set of fields that must be included by an object in order to implement that interface. This helps to maintain a clean schema where certain types have common fields


  • ✅ Prefer:

10. Use Enums in case you expect specific values.

Relying on String type may lead to security issues, unnecessary validation logic on the resolvers side, and a poor developer experience.

Enums types are a special type of scalar that is limited to a particular set of allowable values

This means that wherever we use the type Episode in our schema, we expect it to be exactly one of NEWHOPE, EMPIRE, or JEDI.


To summarize, first, verify that you are using graphql for the correct reasons and that you understand the key concepts. Then, get rid of any preconceptions you might have of your REST build APIs in versions. Then take a step-by-step, customer-centric approach, avoiding premature generalization or undue influence from your background systems.

That’s it

I hope you enjoyed it!

Leave any questions, concerns, recommendations, or criticisms in the comments section. This motivates me to keep improving and writing on Medium

See you later! ❤️




Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Understanding Monolithic Vs Microservice Architecture

A Different Factory Method Pattern Implementation in Java using Jackson

Good Code Should Target Humans

Virtual function calls in constructors and destructors (C++)

Cp210x Virtual Serial Port Drivers For Mac

10 free stock photos you would actually use (Monday 23rd 02PM edition)

How to Get Nice Error Reports Using SARIF in GitHub

Integrating Google Maps API with Unity

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Youssef Hajjari

Youssef Hajjari

More from Medium

GraphQL at Mothership

Optimising Critical Rendering Path

Debugging your SaaS as a Solopreneur — the case for Session Replay tools

Improve Dx and Code Quality With Automated Integration Tests