[V4] [RFC] GraphQL Developer Experience improvements 🥇

[ScottAgirs]

Feature request

Prelude

The below is an opinion. It is based on my experience, may not be complete and I may have missed something, that said I would love for this opinion to be considered, and to hear other people share their thoughts/suggestions.

Summary

After a few of weeks of working with V4 and GraphQL, I've made a decision to scratch those weeks of work and move away from V4 for ' time being.

Below are the biggest pain points that made me do it.

Why is it needed?

After trying to switch to V4 using GraphQL, sadly I've discovered that DX could be muuch better.

GraphQL is not going anywhere and Strapi providing a solid and good DX for GraphQL would surely pave way for a whole ecosystem of new potential users and honour the existing GQL lovers.

Current pain points(s)

1. Defining routes is a pain, especially if compared to what it was like in V3
2. Managing User Permissions is much harder and convoluted (somewhat related to the first pain point)
3. While extending Mutation the way it currently is needed to is not per se Strapi related problem, it would be amazing if Strapi would handle this by simply creating a new resolver (I believe this is somewhat how it worked in V3)
4. The response format is not great for those working with say Apollo Client 3 (or other clients with cache normalization), where the GQL Client relies on a unique identifier inside it GQL type to track the given object. So having the ID inside the attributes would be beneficial. Furthermore the nested data {} inside the response it somewhat verbose and not sure if it's great DX, not only for the sake of the proportionally increasing nullity checks with each nested relation, but also since it - again - increases the complexity for using the GQL Client with cache normalization (this could be solved with something like custom merge functions, but that surely would not be a good DX. Perhaps this could be solved by moving the metadata inside the actual response, say instead of

query {
  posts {
    data {
      id
      attributes {
        title
        ...
      }
    }
    meta {
      pagination {
        ...
      }
    }
  }
}

it could be this:

query {
  posts {
    id
    title
    meta {
      pagination
      ...
    }
  }
}

The approach as in V3 where it was possible to map the same controllers to GraphQL and REST was great, perhaps there is a way to provide same DX with the new engine improvements.

More context

Please don't hate me Strapi folks, you know I love you. But I feel like we're at the point where it's either speak now or forever hold your peace, so. 😄

IMHO, regardless of the fact that (as far as I know) the percentage of current Strapi users for GraphQL is low, it is still a very important piece of the puzzle for a modern headless CMS tool. Furthermore, I believe the number has been historically so low because the DX was not great - now unfortunately it seems it has potentially gotten further from great.

[mattf96s]

Fully agree with the return pattern comments. I'm not seeing the benefit of the overly nested layers + losing Apollo's normalized cache is a massive downside. For a lot of people, this might end up being a choice between using Strapi and using graphql.

[krstivojevicv]

New response format is a huge downside

[Sepifanovskiy]

I`v ended up writing transformer for the response. Unfortunately if I apply it in apollo link it messes up caching so we ended with calling transformer function after each query :(

Data and attributes wrappers are totally unnecessary and only cause problems

[alexandrebodin]

Hello everyone, thank you for these valuable comments.

We created a RFC a few months back to share the context and why we needed those changes and to get ideas/comments on the GraphQL schema here strapi/rfcs#29.

I'll close this issue to keep the issues focused on bugs and will mention it in the RFC to keep everything in a single location.
Please do add more context to your comments there so we can come back to it and see what we can do to improve the pain points.

[alexandrebodin]

@ScottAgirs could you please elaborate in the RFC on the pain point you have with some examples (routes, users & permissions specifically ?)

[ScottAgirs]

Hi @alexandrebodin thank you for your input.

I will do my best to carve out some time.

While we're here, I wanted to also share my thoughts on this flow - since not everybody will intuitively look for Strapi RFC repo and granted that it's been only less than 2 days and there are already supporters of this notion, seeing this as a legitimate issue - humbly, I think leaving this as accessible to Strapi'nauts as possible would be beneficial not only to users but also to Strapi team.

Furthermore, I think one of the reasons why this major change slipped by unnoticed from my radar was because I also often forget about the RFC repo and/or don't find it very convenient to navigate.

Thanks again for taking the time to read this and godspeed with V4 stable launch! 🙌🏼

[alexandrebodin]

Thanks for this remark.

I agree with you that the RFC are not visible enough and we should try to improve this. I'm not going to delete it or anything so if someone finds it they can go to the RFC 👍

And I'll see you there :)