Persisted documents are a great bandwidth optimization, but when used as a "document allow list" (aka "trusted documents" - just those approved by your engineering team) they're also a significant security protection, avoiding the need to protect your endpoint against arbitrary potentially malicious documents.
Not all APIs can support "trusted documents" - the GitHub and Shopify public APIs for example are expected to run queries from untrusted third parties - but most GraphQL APIs are only intended to be used with an organization's own applications (web/mobile/desktop/CLI/service-to-service/etc).
If we launched GraphQL today, given what we know now, I think we would want to make trusted documents the default experience1 so that users were protected by default. Those who wished to accept arbitrary documents could opt into that more dangerous behavior - whether that be for public APIs or just for LLM-written queries - and know that they need to add additional protections.
Since #370 and #379 are proposing dropping backward-compatibility anyway, I thought it would be worth discussing if we should go the whole hog and really encourage the patterns of GraphQL usage we'd like to see by default going forward.
Note: GitHub is currently having an outage w.r.t. seeing pull requests, so I can't pull up the persisted documents, persisted documents URLs, and related PRs currently.
Persisted documents are a great bandwidth optimization, but when used as a "document allow list" (aka "trusted documents" - just those approved by your engineering team) they're also a significant security protection, avoiding the need to protect your endpoint against arbitrary potentially malicious documents.
Not all APIs can support "trusted documents" - the GitHub and Shopify public APIs for example are expected to run queries from untrusted third parties - but most GraphQL APIs are only intended to be used with an organization's own applications (web/mobile/desktop/CLI/service-to-service/etc).
If we launched GraphQL today, given what we know now, I think we would want to make trusted documents the default experience1 so that users were protected by default. Those who wished to accept arbitrary documents could opt into that more dangerous behavior - whether that be for public APIs or just for LLM-written queries - and know that they need to add additional protections.
Since #370 and #379 are proposing dropping backward-compatibility anyway, I thought it would be worth discussing if we should go the whole hog and really encourage the patterns of GraphQL usage we'd like to see by default going forward.
Note: GitHub is currently having an outage w.r.t. seeing pull requests, so I can't pull up the persisted documents, persisted documents URLs, and related PRs currently.
Footnotes
This would also involve improving the tooling and protocols around it, streamlining it to ease usage - something I intend to work on as part of the Golden Path. ↩