Declarative vs Programmatically GraphQL

Question

I´m adopting GraphQL for new fullstack projects and I´ve already studies many of the concepts and started my first projects.

My question is related to use declarative vs programatically GraphQL schema definition. Basically all I can see in the GraphQL official site uses the declarative approach: you define the schema in one or more files like (thanks to this example here):

type Brand {
  name: String
  logoUrl: String
}
enum Gender {
  MALE
  FEMALE
}
type Image {
  thumbnailUrl: String
  smallUrl: String
  mediumUrl: String
  largeUrl: String
}
type Article {
  id: ID! # non-nullable, is guaranteed to exist on every article
  name: String
  thumbnailUrl: String
  brand: Brand
  genders: [Gender]
  images: [Image]
  recommendations: [Article]
}
type Query {
  Article(id: ID!): Article
  Articles: [Articles]
}

Very clean and concise code even for a somehow complex data structure.

But most of examples I see on web and even on books that I´ve studied use the programatically approach to build the schema, something like:

import { GraphQLObjectType, GraphQLInputObjectType } from 'graphql';
import {GraphQLNonNull, GraphQLID, GraphQLList } from 'graphql';
import { GraphQLString, GraphQLInt, GraphQLBoolean } from 'graphql';

import { UserType } from '../User/types';
import UserModel from '../../../models/User';

const fields = {
    _id: {
        type: new GraphQLNonNull(GraphQLID)
    },
    name: {
        type: GraphQLString
    },
    phone: {
        type: GraphQLString
    }
 };

const CompanyType = new GraphQLObjectType({
    name: 'Company',
    description: 'Company',
    fields: fields
 })


const Company = {
    type: CompanyType,
    description: 'Get single company',
    args: {
        id: {
            name: 'id',
            type: new GraphQLNonNull(GraphQLID)
        }
    },
    resolve(root, params) {

        params.deleted = false;

        return CompanyModel.find(params).exec();
    }
}

const Companies = {
    type: new GraphQLList(CompanyType),
    description: 'Get all companies',
    resolve(root) {
        const companies = CompanyModel.find({ deleted: false }).exec();
        if (!companies) {
            throw new Error('Error getting companies.')
        }
        return companies;   
    }
}

export default {
    Company,
    Companies
}

My goal is to build a large SaaS application, so the schema will get pretty complex and my worry is that the code gets complex pretty soon.

So, should I go for a declarative approach, a programmatically approach or a mix of two?

What is the best practices here?

user_11586487 · Answer

Declarative == Full-schema (or schema-first).
Programmatically == Object-based (or code first).

for the post below.

"Completely relying on the full-schema text to create a GraphQL schema has a few drawbacks. You’ll need to put in some effort to make the code modularized and clear, and you’ll have to rely on coding patterns and tools to keep the schema-language text consistent with the tree of resolvers (aka resolvers map). These are solvable problems.

The biggest issue I see with the full-schema method is that you lose some flexibility in your code. All your types have to be written in that specific way that relies on the schema-language text. You can’t use constructors to create some types when you need to. You’re locked into this string-based approach. Although the schema-language text makes your types more readable, in many cases, you’ll need flexibility over readability.

The object-based method is flexible and easier to extend and manage. It does not suffer from any of the problems I just mentioned. Your code will be modular with it because your schema will be a bunch of objects. You also don’t need to merge modules, because these objects are designed and expected to work like a tree.

The only issue I see with the object-based method is that you have to deal with a lot more code around what’s important to manage in your modules (types and resolvers). Many developers see that as noise, and I do not blame them.

If you’re creating a small, well-defined GraphQL service, using the full-schema-string method is probably okay. However, in bigger and more agile projects, I think the more flexible and powerful object-based method is the way to go."

Source

Declarative vs Programmatically GraphQL

3 Answers