update README

Author: Alex Langenfeld

README.md

@@ -53,6 +53,16 @@ The `graphqlHTTP` function accepts the following options:
   * **`graphiql`**: If `true`, may present [GraphiQL][] when loaded directly
     from a browser (a useful tool for debugging and exploration).
 
+  * **`loadPersistedDocument`**: A function that takes an input id and returns a
+    valid Document. If provided, this will allow your GraphQL endpoint to execute
+    a document specified via `documentID`.
+
+  * **`persistValidatedDocument`**: A function that takes a validated Document and
+    returns an id that can be used to load it later. This is used in conjunction
+    with `loadPersistedDocument`. Providing this function will enable persisting
+    documents via the `document` parameter at the `/persist` subpath. It is
+    recommended that this option only be enabled in development deployments.
+
 
 ## Debugging
 
@@ -156,6 +166,22 @@ new GraphQLObjectType({
 });
 ```
 
+## Persisted Documents
+
+Putting control of the query in to clients hands is one of the primary benefits
+of GraphQL. Though when this is deployed to production naively, it is possible to
+end up uploading and revalidating the same document text across all clients of a
+particular deployment. It can even be problematic within a single client, sending
+the exact same query repeatedly. Uploading and validating a large GraphQL document
+can be very costly, especially over a poor network connection from a mobile device
+with something large and complex such as Facebook's News Feed GraphQL query.
+
+One solution to this problem that was developed early in the use of GraphQL at
+Facebook was persisted documents. At build time, we take the GraphQL document and
+persist it on the server getting back an ID. Then at runtime, we only upload the
+ID of the document and the variables. When the server receives this request, it
+loads the query and executes it, knowing it was already validated.
+
 [`graphql-js`]: https://github.com/graphql/graphql-js
 [`formatError`]: https://github.com/graphql/graphql-js/blob/master/src/error/formatError.js
 [GraphiQL]: https://github.com/graphql/graphiql