31 Jul 2023
In this post, 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.
{
articles {
id
}
}
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.
{
getArticles {
id
}
}
Next, we have domain-specific queries like drafts or published. 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.
{
drafts {
id
}
publisheed {
id
}
pending {
id
}
}
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.
{
articleCollection {
id
}
}
"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.
{
allArticles {
id
}
}
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 — articles.
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, be consistent.