guides

GraphQL API Schemas: Designing a better one

Schemas are an important part of building a graph. They are one of the main advantages of using GraphQL.

introduction

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:

• One Data Graph for All
• No Over-Fetching or Under-Fetching
• Higher Quality of Your System
• Better Developer Experience

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

Example:

• ❌ 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.

Example:

• ❌ Instead of:

• ✅ Prefer:

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.

Example:

• ❌ 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.

Example:

• ❌ Instead of:

• ✅ Prefer:

7. Spacing between field descriptions.

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

Why: Easily readable!

Example:

• ❌ 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

Example:

• ✅ 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.

Conclusion:

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! ❤️