search

mondaycom / monday-graphql-api

4 stars 2 forks source link

implement separate query and mutation methods #30

Open codyfrisch opened 2 months ago

codyfrisch commented 2 months ago

Typically GraphQL clients provide a query and mutation method, since the return types for each are different bases.

I know this project is still in development.

Typically there would be an .api() method which takes a generic type like the current query. Then .query() would have its generic type default to Query and .mutation() has a generic with a default of Mutation.

This way even if a user doesn't create a type for Query or Mutation, the returned types are at least relevant.

RomKadria commented 3 weeks ago

Hey, we thought about that initially but since the return type here depends on the return type, didn't find a benefit for it. can you give me an example for a scenario where mutation or query will be helpful here as distinction? because all it does is make the request - therefore the wording wont matter.

codyfrisch commented 3 weeks ago

Mostly its convention from ApolloClient. Having it adhere to conventions makes it easier for developers to pick it up. If the only method was called .request() like graphql-request that would be fine, but since its .query() its now inferring its following the Apollo standard instead and developers will expect a corresponding .mutation() method. Presuming they have any experience with either. (Then again the majority I see in the community cannot understand its not a REST API even after explaining it)

For devs experienced with GraphQL, the monday API has been a bit of a pain because the tooling, and the API itself has strayed from the norms of GraphQL in the past. It has made the learning curve steeper than necessary (it should be about learning the different queries and mutation, not different flavor of GraphQL development)

Just trying to shorten the learning curve (even just a little) for devs who are dropping into the ecosystem to integrate monday with a customers random backend system. Very common.

RomKadria commented 2 weeks ago

I understand and totally agree :) we are on actively trying to make the api easier to learn, use, understand.

I understand why the query keyword can be confusing here. but since if il add the mutation one itl do the same thing, its too redundant to separate for readability (IMO). If you think its too confusing and have suggestions to a better word that'l suit both, il be happy to hear and consider :)