RFC: Fully Qualified Operation Names #1185
Description
👋 Not sure where this should go exactly, perhaps the over-http spec since that's where we previously talked about persisted operations? This feels like a companion spec to persisted operations, and something many folks probably have custom solutions for, and arguably worth standardizing.
When using Persisted Operations, we may identify queries in two different ways:
- The "query name" (e.g.
GetConsumerHeaderData) - The "operation id" (e.g.
605fad0ee0a88...)
At Yelp, when referencing a query in service logs, dashboards, urls etc, we use the Operation ID only.
This is because query names are not guaranteed to be unique - the same query name can be used across platforms, within the same monorepo, or even different versions of the same query. The footgun is that a developer might see "GetUserInfo" in logs, copy and paste that string, use git grep and find it in the codebase -- only to later discover it's the wrong GetUserInfo query!
Using an Operation ID guarantees that when folks copy and paste an identifier to look up the query definition, they'll find the correct query. To reduce the likelihood of this footgun occurring, our tooling splits out Operation IDs exclusively where possible.
However...
It does make certain use cases difficult - for example, configuring alerting by operation requires that you update the config file with the new operation id each time a new version of the query is published.
Proposal: Fully Qualified GraphQL Operation Name
A Fully Qualified GraphQL Operation Name (FQON??) is a human readable alternative to Operation IDs that can provide the same guarantee of uniqueness, and can be used partially to omit the version number in such cases as alert config files.
The format will be:
name:project:repo:version
This is enough information to unambiguously identify the exact document (assuming the library handling persisted operations guarantees no duplicate query names per project).
Example:
GetConsumerHeaderData:yelp-styleguide:yelp/frontend:3
The right hand side components of the FQON can be omitted for a partial match:
Example
GetConsumerHeaderData:yelp-styleguide:yelp/frontend
^ this will match any version of the "same" query
ARN Syntax
: as a seperator is inspired by ARNs
Omitting sections
ARNs allow for omitting certain sections where appropriate. Similarly, if a repo is not set up as a monorepo, it may want to omit the project section (but reserve the section for later usage)
Example
GetConsumerHeaderData::yelp/frontend:3
Wildcards
Wildcards may be used when "searching" for operations and supported by tooling.
Omitting the version section (rather than using a wildcard) is also special-case supported to simplify alerting pipelines that may not support interpreting a wildcard match.