GraphQL Naming Conventions

This document describes the GraphQL's Naming Conventions
Case styles
Field names should use camelCase. Many GraphQL clients are written in JavaScript, Java, Kotlin, or Swift, all of which recommend camelCase for variable names.
Type names should use PascalCase. This matches how classes are defined in the languages mentioned above.
Enum names should use PascalCase.
Enum values should use ALL_CAPS, because they are similar to constants.
Examples
1
type Dog {
2
  id: String!
3
}
4
​
5
query DogQuery {
6
  dog {
7
    id
8
  }
9
}
10
​
11
enum Animal {
12
  DOG
13
  CAT
14
}
Copied!
Input objects naming conventions
Use a single, required, unique, input object type as an argument for easier execution on the client.
1
query DogQuery {
2
  dog(input: DogQueryInput!) {
3
    id
4
  }
5
}
6
​
7
mutation PetDogMutation {
8
  petDog(input: PetDogInput!) {
9
    id
10
  }
11
}
Copied!
Query naming conventions
GraphQL is about asking for specific fields on objects, therefore it's essential that the query has exactly the same shape as the result. Naming queries the same as the type will help with that:
1
query {
2
  dog {
3
    id
4
  }
5
}
Copied!
will result in:
1
data {
2
  dog {
3
    id
4
  }
5
}
Copied!
You can make a sub-selection of fields for that object. GraphQL queries can traverse related objects and their fields.
1
query {
2
  dog {
3
    id
4
    owner {
5
      id
6
    }
7
  }
8
}
Copied!
Fetching array of items
GraphQL list queries work quite differently from single field queries. We know which one to expect based on what is indicated in the schema, which will be denoted by a plural name.
The pagination structure should follow a simplified version of the Relay's connection pattern.
1
query {
2
  dog {
3
    id
4
    owners(first: 10, after: $endCursor) {
5
      count
6
      items {
7
        id
8
      }
9
      pageInfo {
10
        hasNextPage
11
        endCursor
12
      }
13
    }
14
  }
15
}
Copied!
Mutation naming conventions
Make mutations as specific as possible. Mutations should represent semantic actions that might be taken by the user whenever possible.
Name your mutations verb first. Then the object, or “noun,” if applicable; createAnimal is preferable to animalCreate.
1
mutation {
2
  createAnimal(input: CreateAnimalInput!) {
3
    id
4
  }
5
}
Copied!
Integrating naming conventions into shared api
Now for the hard part!
Since all of our resolvers will be merged into a shared api, we need to come up with a system to avoid overwriting previous resolvers. Let's take this example to understand the problem better.
We have two projects, ProjectX and ProjectY. Both of these projects need to query a user, but the user type references a different resource.
1.ProjectX's resolvers are merged first with the user query that fetches users from the National Registry.
2.ProjectY's resolvers are merged after with the user query that fetches users from the RSK.
Here the ProjectY's user query will overwrite the ProjectX's query and will break ProjectX.
Solution
We need to prefix all Mutations, Queries, Types, Scalars, etc. with the name of the module that is merged into the api.
Mutations should still follow the verb first rule. Then the module name, following the object, or “noun,” if applicable.
Exception to the solution
If the name of the GraphQL type/query/mutation is the same as the module, then we don't need the prefix.
Example
1
type ProjectXUser {
2
  id: String!
3
}
4
​
5
query {
6
  projectXUser {
7
    id
8
  }
9
}
10
​
11
mutation {
12
  createProjectXUser {
13
    id
14
  }
15
}
Copied!
1
# here we are working in the identity module, thus we won't name our type IdentityIdenty. Same exception applies for query/mutation
2
​
3
type Identity {
4
  id: UUID!
5
}
6
​
7
query {
8
  identity {
9
    id
10
  }
11
}
12
​
13
mutation {
14
  createIdentity {
15
    id
16
  }
17
}
Copied!
Conclusion
With these design principles you should be equipped to design an effective GraphQL system for your API.

Example API Service

HTTP Status Response Codes

Last modified 2mo ago

Copy link

Contents

Case styles

Examples

Input objects naming conventions

Query naming conventions

Fetching array of items

Mutation naming conventions

Integrating naming conventions into shared api

Solution

Conclusion