Suggestions: basic/advanced/experimental patterns

[SachaG]

To make it easier to reach consensus on specific patterns, I think it could be useful to tag them according to their "status". What I have in mind would be:

• Basic: patterns or best practices that nearly everybody agrees on and that should probably be implemented by most GraphQL projects.
• Advanced: patterns or practices that people agree on, but might not be needed by every project. For example, something like cursor-based pagination.
• Experimental: patterns that some people find useful, but haven't reached a consensus yet; or maybe go against the GraphQL spec somehow.

Having this "experimental" designation would make it easier to include new patterns even if people don't unanimously approve of them. They could always "graduate" to basic or advanced later on once they become more widespread.

Thoughts?

[RIP21]

Totally agree, that would be nice. Because implementing all the amazing tricks described there is not needed for sure, but having a distinctions like that for newcomers would be amazing.
There was also a plan to build some sort of picker mode. Where teams can pick the rules they are using, and then generate their own "cheatsheet".

PS. Thanks for state of JS ;)

[SachaG]

Picker mode would be cool! You could then generate stats to see which patterns are used the most. I expect it would require a lot more back-end complexity to track that data though…

And thanks, stay tuned for the 2019 edition soon (which I should be working on right now instead of doing this actually…)

[nodkz]

I agree with basic and advanced but don't feel that experimental name is good enough.

For now, we have the following set of rules. And which tags do you want to set for every rule? Maybe you will found new tags ;)

• 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, is 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

[nodkz]

Anyway tags addition is a great idea 👍

In the future, we can add more tags with different meanings and allow users to filter rules by them. Eg. mutation, query, filtering, auth, args, convention etc.

But first, need to choose good values for pattern tagging.

[SachaG]

I agree with basic and advanced but don't feel that experimental name is good enough.

What's the word that other specs use when something is under review or not yet officially accepted? Under consideration? Under review?