graphql-over-http icon indicating copy to clipboard operation
graphql-over-http copied to clipboard

Published 20 hours ago • verified publisher icon graphql

[RFC] Add Appendix A: Persisted Documents

Open benjie opened this issue 2 years ago • 8 comments

Addresses #38 (though not the "automatic" version; though that can be built on top of this spec).

This is a first draft.

benjie avatar Oct 09 '23 12:10 benjie

I think the RFC document still warrants discussion; let's leave it until after the meeting.

benjie avatar Oct 09 '23 12:10 benjie

Added to October 26th agenda: https://github.com/graphql/graphql-over-http/blob/main/working-group/agendas/2023/2023-10-26.md

benjie avatar Oct 09 '23 12:10 benjie

Thanks for your feedback everyone! I've adopted some of the feedback and replied to others. Keep it coming!

benjie avatar Oct 10 '23 13:10 benjie

I've also written a piece on "trusted documents" - essentially the type of persisted documents that you can build an allowlist with (also known as "persisted queries" and various other names):

https://benjie.dev/graphql/trusted-documents

My hope is that "trusted documents" can become the preferred term when persisted documents are used as an allowlist (i.e. where your developers have written them), since it cannot be confused with other techniques such as "automatic persisted queries" (APQ), since these techniques involve no trust.

benjie avatar Oct 12 '23 15:10 benjie

Regarding documentId, would it make sense to add it to the main spec spec page as well? Somewhere around here, in the "Request parameters" section?

If documentId is a reserved key, might as well allocated it in the main spec page? Going to an appendix for that feels a bit off.

martinbonnin avatar Oct 12 '23 16:10 martinbonnin

@martinbonnin I see what you mean, but documentId is meaningless to a GraphQL-over-HTTP request; it's only relevant to a persisted document request. I guess we could add it as a "reserved key" ("a GraphQL-over-HTTP request must never contain a property documentId"); but at the moment all unspecified keys are effectively reserved (if you need to add a key, it should go in extensions) so that seems redundant.

benjie avatar Oct 13 '23 10:10 benjie

@benjie right. Maybe "Appendix B: Reserved keys" 🙃? I don't really know... It'd be interesting to compare to what other protocols with optional features have done in the past. I don't have an example at hand right now but I'll keep looking.

martinbonnin avatar Oct 13 '23 11:10 martinbonnin

This RFC for Persisted Documents as currently written is now supported in GraphQL.NET 8.0.1 and GraphQL.NET Server 8.0.1. Please try it out!

Notes:

  • Supported for GET, JSON POST, url-encoded POST (when enabled), multipart POST (when enabled), and websocket requests (both subscriptions-transport-ws and graphql-ws)
  • No automatic persisted query support has been added for this spec
  • Apollo Automatic Persisted Queries are still supported using the old spec (within extensions)
  • Does not yet support url path parsing such as demonstrated in #305
  • Does not restrict character sets for document identifiers (see #296 )

Non-breaking changes to this RFC will be implemented within GraphQL.NET as needed/requested on an ongoing basis. Breaking changes within GraphQL.NET occur only upon major version releases.

Shane32 avatar Aug 23 '24 20:08 Shane32