@@ -97,34 +97,36 @@ MD5 hash of the GraphQL document, as traditionally used by Relay.
9797
9898## Persisting a Document
9999
100- A client that wishes to utilize persisted documents for a request must generate
101- a _ document identifier_ for the associated GraphQL Document and should ensure
102- the server can retrieve this GraphQL Document from the document identifier. The
100+ To utilize persisted documents for a request, the client must possess a unique
101+ _ document identifier_ for the associated GraphQL Document, and the server must
102+ be able to retrieve this GraphQL Document using the document identifier. The
103103method through which the client and server achieve this is implementation
104104specific.
105105
106106Note: When used as an operation allow-list, persisted documents are typically
107- stored into a trusted shared key-value store at client build time
108- (either directly, or indirectly via an authenticated request to the server) such
109- that the server may retrieve them given the identifier at request time. This
110- must be done in a secure manner (preventing untrusted third parties from adding
111- their own persisted document) such that the server will be able to retrieve the
107+ stored into a trusted shared key-value store at client build time (either
108+ directly, or indirectly via an authenticated request to the server) such that
109+ the server may retrieve them given the identifier at request time. This must be
110+ done in a secure manner (preventing untrusted third parties from adding their
111+ own persisted document) such that the server will be able to retrieve the
112112identified document within a _ persisted document request_ and know that it is
113113trusted.
114114
115- Note: When used solely as a bandwidth optimization, an error-based mechanism
115+ Note: When used solely as a bandwidth optimization, as in the technique known
116+ colloquially as "automatic persisted queries (APQ)," an error-based mechanism
116117might be used wherein the client assumes that the document has already been
117118persisted, but if the request fails due to unknown _ document identifier_ the
118119client issues a follow-up request containing the full GraphQL Document to be
119120persisted.
120121
121- Note: When persisting a document it is generally good practice for the client to
122- issue both the GraphQL Document and the document identifier to the server; the
123- server would then regenerate the document identifier from the GraphQL Document
124- independently, and check that the identifiers match before storing the Document.
125- An alternative but equally valid approach has the client issue the GraphQL
126- Document to the server, and the server returns an arbitrary _ custom document
127- identifier_ that the client would incorporate into its bundle.
122+ Note: When persisting a document for which the identifier has been derived by
123+ the client, it is generally good practice for the client to issue both the
124+ GraphQL Document and the document identifier to the server; the server could
125+ then regenerate the document identifier from the GraphQL Document independently,
126+ and check that the identifiers match before storing the Document. If the
127+ identifier is not derived on the client then the client must coordinate
128+ retrieval of a document identifier from the server to be incorporated into the
129+ deployed client.
128130
129131## Persisted Document Request
130132
@@ -263,7 +265,7 @@ _persisted document request_, it must return a well‐formed _GraphQL response_.
263265
264266The server should retrieve the GraphQL Document identified by the {documentId}
265267parameter. If the server fails to retrieve the document, it MUST respond with a
266- well-formed _ GraphQL response_ consisting of a single error. Otherwise, it
267- should construct a _ GraphQL-over-HTTP request_ using this document and the other
268+ well-formed _ GraphQL response_ consisting of a single error. Otherwise, it will
269+ construct a _ GraphQL-over-HTTP request_ using this document and the other
268270parameters of the _ persisted document request_ , and then follow the details in
269271the [ Response section] ( #sec-Response ) .
0 commit comments