GraphQL Rules
  • 1. Naming rules
    • 1.1. Use camelCase for GraphQL-fields and arguments.
    • 1.2. Use UpperCamelCase for GraphQL-types.
    • 1.3. Use CAPITALIZED_WITH_UNDERSCORES to name ENUM-types.
  • 2. Type rules
    • 2.1. Use custom scalar types if you want to declare fields or args with specific semantic value.
    • 2.2. Use Enum for fields which contain a specific set of values.
  • 3. Field Rules (Output)
    • 3.1. Use semantic names for fields and avoid leaking of implementation details in fields names.
    • 3.2. Use Non-Null field if field will always have a given field value.
    • 3.3. Group as many related fields into custom Object type as possible.
  • 4. Argument rules (Input)
    • 4.1. Group coupled arguments to the new input-type.
    • 4.2.Use strict scalar types for arguments, eg. DateTime instead of String.
    • 4.3. Mark arguments as required if they are required for query execution.
  • 5. Rules of lists
    • 5.1. To filter the lists, use the filter argument, which contains all the available filters.
    • 5.2. Use argument sort of type Enum or [Enum!] for listings sorting.
    • 5.3. Use limit with default value and skip to limit number of returned items in list.
    • 5.4. Use page, perPage args for pagination and return output type with items (array of elements) and pageInfo (meta-data).
    • 5.5. For infinite lists (infinite scroll) use Relay Cursor Connections Specification.
  • 6. Mutation rules
    • 6.1. Use Namespace-types to group mutations within a single resource.
    • 6.2. Go beyond CRUD – create small mutations for different business operations on resources.
    • 6.3. Consider the ability to perform mutations on multiple items (same type batch changes).
    • 6.4. Mutations should clearly describe all the mandatory arguments, there should be no options either-either.
    • 6.5. In mutations, put all variables into one unique input argument.
    • 6.6. Every mutation should have a unique payload type.
      • 6.6.1. In the mutation response, return the modified resource and its id.
      • 6.6.2. Return operation status in mutation response.
      • 6.6.3. In the mutation response, return a field of type Query.
      • 6.6.4. In the mutation response, return the errors field with typed user errors.
  • 7. Rules of linkages between types (relationships)
    • 7.1. GraphQL schema should be "hairy"
  • 8. Authorization
    • 8.1. Schema diffing based authorization
  • 10. Other rules
    • 10.1. Use markdown for documentation
  • A. Appendix
    • A-1 Useful links
  • Credits
Edit page
4. Argument rules
4.1. Group coupled arguments to the new input-type.
4.2. Use strict scalar types for arguments, eg. DateTime instead of String.
4.3. Mark arguments as required if they are required for query execution.
CC-BY-4.0 2022, @nodkz and awesome folks