graphql

GraphQL Best Practices

This guide outlines the definitive best practices for designing, implementing, and operating GraphQL APIs. Adhere to these rules to ensure your schemas are consistent, performant, secure, and developer-friendly.

1. Schema Design & Naming Conventions

Consistency is paramount. Follow standard GraphQL naming conventions strictly.

1.1 Casing Rules

• Types (Object, Input, Enum, Interface, Union, Scalar): PascalCase
• Fields, Arguments, Directives: camelCase
• Enum Values: SCREAMING_SNAKE_CASE

❌ BAD

type user { # Type name not PascalCase
  firstName: String!
  getProducts(productId: ID): [product] # Field name has verb, arg not camelCase
}

enum UserRole { # Enum value not SCREAMING_SNAKE_CASE
  admin
  guest
}

✅ GOOD

type User {
  id: ID!
  firstName: String!
  products(limit: Int): [Product!]! # No verb, arg is camelCase
  role: UserRole!
}

enum UserRole {
  ADMIN
  GUEST
}

1.2 Query Field Naming

Avoid verb prefixes (get, list, fetch) on query (read) fields. This maintains consistency with nested fields.

❌ BAD

type Query {
  getUsers: [User!]!
  listProducts: [Product!]!
}

query MyQuery {
  getUsers {
    id
    getProducts { # Inconsistent with root field
      name
    }
  }
}

✅ GOOD

type Query {
  users: [User!]!
  products: [Product!]!
}

query MyQuery {
  users {
    id
    products { # Consistent with root field
      name
    }
  }
}

1.3 Mutation Field Naming

Start mutation fields with an imperative verb (e.g., create, update, delete).

❌ BAD

type Mutation {
  userCreate(input: CreateUserInput!): CreateUserPayload!
}

✅ GOOD

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(input: UpdateUserInput!): UpdateUserPayload!
  deleteUser(input: DeleteUserInput!): DeleteUserPayload!
}

1.4 Input & Payload Types

• Input Types: Suffix with Input.
• Mutation Payload Types: Suffix with Payload or Response. These should typically include the created/updated object and a success boolean or errors array.