Skip to content

Commit 52d56fb

Browse files
committed
Adopt some changes recommended via review
1 parent 6fbc6ed commit 52d56fb

File tree

1 file changed

+20
-18
lines changed

1 file changed

+20
-18
lines changed

spec/Appendix A -- Persisted Documents.md

+20-18
Original file line numberDiff line numberDiff line change
@@ -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
103103
method through which the client and server achieve this is implementation
104104
specific.
105105

106106
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
112112
identified document within a _persisted document request_ and know that it is
113113
trusted.
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
116117
might be used wherein the client assumes that the document has already been
117118
persisted, but if the request fails due to unknown _document identifier_ the
118119
client issues a follow-up request containing the full GraphQL Document to be
119120
persisted.
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

264266
The server should retrieve the GraphQL Document identified by the {documentId}
265267
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
268270
parameters of the _persisted document request_, and then follow the details in
269271
the [Response section](#sec-Response).

0 commit comments

Comments
 (0)