v2 Proposal: GraphQL Schema Adjustments to Align with GraphQL Best Practices

[acomagu]

I've evaluated many Headless CMSs as potential migration targets from Strapi for our product. We're currently leaning towards adopting Payload CMS.

However, I've observed a few peculiarities in Payload CMS's GraphQL implementation that set it apart from other CMSs. These might seem minor, but addressing them can make migrations smoother for many.

• Query object field names are in PascalCase rather than camelCase (e.g., Query.User).
• Collection list results are nested under a 'docs' field (e.g., one must traverse through Query.Users.docs to access the actual objects).
• When querying, if the specified object doesn't exist, it returns an error instead of null.

These nuances appear to be a reflection of a REST API structure. However, adhering to commonly accepted GraphQL best practices can make the API more intuitive for newcomers and facilitate migrations from other CMSs

For instance, another Headless CMS named Hygraph doesn't exhibit these issues. Given that it was designed with a GraphQL-first approach, it can be a useful reference for design.

Additionally, there's OpenCRUD, which aims to establish a standard for GraphQL APIs across all Headless CMSs. Several CMSs have already aligned with it, making it a valuable reference for API design.

With this in mind, here are my proposed design modifications:

• All fields under the Query object are in camelCase.
• For queries that return multiple objects, return the list directly without interjecting a Pager Object.
• Return null instead of a NotFoundError when an object doesn't exist (as per GraphQL best practices)
• Optional: For use-cases that require detailed paging results, provide a field compatible with Relay's Cursor Connection as Query.<Collection Name>Connection field (an idea from OpenCRUD).

For clarity, here's a representation of what it might look like:

type Query {
  user(
    id: String!,
    draft: Boolean,
    locale: LocaleInputType,
    fallbackLocale: FallbackLocaleInputType,
  ): User
  
  users(
    where: User_where,
    draft: Boolean,
    locale: LocaleInputType,
    fallbackLocale: FallbackLocaleInputType,
    page: Int,
    limit: Int,
    sort: String,
  ): [Users!]
  
  usersConnection(
    where: User_where,
    draft: Boolean,
    locale: LocaleInputType,
    fallbackLocale: FallbackLocaleInputType,
    page: Int,
    limit: Int,
    sort: String,
  ): UsersConnection!
}

I understand there might be concerns about migrating from the current Payload setup, but I think it's also important to make transitions from other CMSs seamless, as well as provide an API without surprises for those experienced with GraphQL.

Thank you for your consideration.

[tyteen4a03]

+1 - would be good for the GraphQL API to be Relay-spec compliant!