graphql
RFC: Fully Qualified Operation Names
👋 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 "document id" (e.g.
605fad0ee0a88...)
At Yelp, when referencing a query in service logs, dashboards, urls etc, we use the Document 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 Document 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 Document 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 document 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.
On a related note, I think we're going to recommend that the URLs be /graphql/persisted/<DOC_ID>/<OPERATION_NAME> - see https://github.com/graphql/graphql-over-http/pull/305/files#r1706576324
As such, overlapping the DOC_ID and OPERATION_NAME may be a smidge redundant; but I don't think that's a huge deal.
@benjie where does Appendix A -- Persisted Documents.md actually live now btw? was trying to find that earlier
@magicmark It's not merged yet, but the first draft is in https://github.com/graphql/graphql-over-http/pull/264 which is then extended by https://github.com/graphql/graphql-over-http/pull/305
I love this!
Minor proposal to simplify even more with:
name:clientId:version
The clientId could be anything that uniquely identifies a client. If users want to encode the project/repo, they could go with things like yelp-styleguide:yelp/frontend but it's not a strong requirement. Different users could encode different things.
