Don’t Make them Tell you Thrice

Here’s an API design pattern that drives me a little nuts.

If you’re using the Apollo GraphQL client to make a data fetching query, your code looks like this.

client.query({
    query: gql`query { ... your query here ...}`
}

However, if you’re using the apollo client to make a graphql mutation query, your code looks like this

// while I'm here can I gripe about the rise in popularity of the
// word "mutate" to mean "changes the value"
client.mutate({
    mutation: gql`mutation { ... your query here ...}`
}

As a client developer who wants to make a graphql query, I end up needing to say whether I want to mutate or query three times.

First, in the query itself

mutation { ... your query here ...}
query { ... your query here ...}    

Second, in the object that’s passed to the API method

{query: ...}
{mutation: ...} 

and finally, in the method name itself.

client.query    
client.mutate

This sort of triple redundancy makes learning how to use the API a bit more difficult (as seen in this stack overflow question/answer pair), and also adds a bit more contextual overhead to folks trying to use the API.

Easy enough to shrug off in this one case, but in aggregate this sort of thing is a big part of why systems are increasingly fragile and humans are increasingly unable to understand the systems we’ve built.