Add documentation for Subscriptions

Summary:
Also included an example of adding a new node to a connection :-)
Closes #1772

Reviewed By: kassens

Differential Revision: D5078598

Pulled By: josephsavona

fbshipit-source-id: 235c69e07c70ae629d2dc1193b23565ce2c7e2b3

docs/modern/Mutations.md

@@ -4,7 +4,7 @@ title: Mutations
 layout: docs
 category: Relay Modern
 permalink: docs/mutations.html
-next: babel-plugin-relay
+next: subscriptions
 ---
 
 Relay exposes the following APIs to perform mutations.

docs/modern/Subscriptions.md

@@ -0,0 +1,115 @@
+---
+id: subscriptions
+title: Subscriptions
+layout: docs
+category: Relay Modern
+permalink: docs/subscriptions.html
+next: babel-plugin-relay
+---
+
+Relay exposes the following APIs to create subscriptions.
+
+```javascript
+const {requestSubscription} = require('react-relay');
+
+type Variables = {[name: string]: any};
+
+requestSubscription(
+  environment: Environment,
+  config: {
+    subscription: GraphQLTaggedNode,
+    variables: Variables,
+    onCompleted?: ?() => void,
+    onError?: ?(error: Error) => void,
+    onNext?: ?(response: ?Object) => void,
+    updater?: ?(store: RecordSourceSelectorProxy) => void,
+  },
+);
+```
+
+Now let's take a closer look at the `config`:
+
+* `subscription`: the `graphql` tagged subscription query.
+* `variables`: an object that contains the variables needed for the subscription.
+* `onCompleted`: a callback function executed when the subscription is closed by
+  the peer without error. 
+* `onError`: a callback function executed when Relay or the server encounters an
+  error processing the subscription. 
+* `onNext`: a callback function executed each time a response is received from
+  the server, with the raw GraphQL response payload.
+* `updater`: an optional function that can supply custom logic for updating the
+  in-memory Relay store based on the server response.
+
+## Example
+
+In a simple subscription, you only need `subscription` and `variables`. This is
+appropriate when you are only changing the properties of existing records that
+can be identified by their `id`:
+
+```javascript
+const {
+  requestSubscription,
+  graphql,
+} = require('react-relay');
+
+const subscription = graphql`
+  subscription MarkReadNotificationSubscription(
+    $storyID: ID!
+  ) {
+    markReadNotification(storyID: $storyID) {
+      notification {
+        seenState
+      }
+    }
+  }
+`;
+
+const variables = {
+  storyID,
+};
+
+requestSubscription(
+  yourEnvironment, // see Environment docs
+  {
+    subscription,
+    variables,
+    // optional but recommended:
+    onComplete: () => {/* server closed the subscription */},
+    onError: error => console.error(error),
+  }
+);
+```
+
+# Updating the client on each response
+
+For more complex use-cases, you may wish to perform custom logic to update 
+Relay's in-memory cache when each subscription response is received. To do so,
+pass an `updater` function:
+
+```javascript
+const {ConnectionHandler} = require('relay-runtime');
+
+requestSubscription(
+  environment,
+  {
+    subscription,
+    variables,
+    updater: store => {
+      // Get the notification
+      const rootField = store.getRootField('markReadNotification');
+      const notification = rootField.getLinkedRecord('notification');
+      // Add it to a connection
+      const viewer = store.getRoot().getLinkedRecord('viewer');
+      const notifications = 
+        ConnectionHandler.getConnection(viewer, 'notifications');
+      const edge = ConnectionHandler.createEdge(
+        store, 
+        notifications,
+        notification, 
+        '<TypeOfNotificationsEdge>',
+      );
+      ConnectionHandler.insertEdgeAfter(notifications, edge);
+    },
+  },
+);
+```