GraphQL list query naming conventions

In this episode, we’ll explore some of the different naming conventions for querying lists of items.

Plural queries like "articles." They communicate clearly that the response will contain a collection of items, and the name itself is concise and straightforward.

Moving on to action-based queries such as "getArticles." These indicate that the aim is to retrieve something without any side effects. It's worth noting though, that this can be seen as redundant, since by nature, GraphQL queries are used to fetch data.

Next, we have domain-specific queries. These provide a clear indication of the type of items that will be returned. They prove extremely useful when working with queries that return multiple types, especially with GraphQL union types.

Then we come to queries with a collection suffix, like "articleCollection." These clearly highlight that the query will return a collection of items. However, the term "collection" can often be redundant, leading to a longer query name.

"All" prefix queries such as "allArticles" emphasize that all entries for a specific type are being queried. However, it could potentially cause confusion if a filter argument is passed, leading to not "all" items being returned.

In the end, the choice of naming convention is up to you when designing a schema. But the most common and arguably the most intuitive approach is the plural format. It’s clean, concise, and easily identifiable based on the entity it represents. Adding arguments to filter, limit, and skip records creates little ambiguity, making it clear what the query will return.

Whatever you decide, be consistent. If you decide to use something a little unconventional or ugly, be consistent.

[davidhavl]

Naming things is often the hardest thing about development. Thank you Jamie!