@@ -97,34 +97,36 @@ MD5 hash of the GraphQL document, as traditionally used by Relay.
97
97
98
98
## Persisting a Document
99
99
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
103
103
method through which the client and server achieve this is implementation
104
104
specific.
105
105
106
106
Note: 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
112
112
identified document within a _ persisted document request_ and know that it is
113
113
trusted.
114
114
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
116
117
might be used wherein the client assumes that the document has already been
117
118
persisted, but if the request fails due to unknown _ document identifier_ the
118
119
client issues a follow-up request containing the full GraphQL Document to be
119
120
persisted.
120
121
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.
128
130
129
131
## Persisted Document Request
130
132
@@ -263,7 +265,7 @@ _persisted document request_, it must return a well‐formed _GraphQL response_.
263
265
264
266
The server should retrieve the GraphQL Document identified by the {documentId}
265
267
parameter. 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
268
270
parameters of the _ persisted document request_ , and then follow the details in
269
271
the [ Response section] ( #sec-Response ) .
0 commit comments