Content edit for subscriptions article #4880
Conversation
docs/source/data/subscriptions.mdx
Outdated
|
|
||
| import {ExpansionPanel} from 'gatsby-theme-apollo-docs'; | ||
|
|
||
| > **Subscriptions are not supported in [Apollo Federation](https://www.apollographql.com/docs/federation/).** |
docs/source/data/subscriptions.mdx
Outdated
|
|
||
| > **Subscriptions are not supported in [Apollo Federation](https://www.apollographql.com/docs/federation/).** | ||
|
|
||
| **Subscriptions** are GraphQL operations that maintain an active connection between client and server. This enables your server to _push_ updates to a subscription's result as they occur, instead of requiring your client to _poll_ for updates. |
There was a problem hiding this comment.
I don't think maintaining an active connection is what defines subscriptions. What differentiates them from queries is that they are triggered by events, and they generate a new result for each such event. Although delivering results as soon as they are generated works best over a persistent connection, there is nothing stopping you from implementing subscriptions on top of polling.
docs/source/data/subscriptions.mdx
Outdated
|
|
||
| ## Schema definition | ||
|
|
||
| You define your schema's supported subscriptions as fields of the `Subscription` type: |
There was a problem hiding this comment.
This may not be a distinction we care about, but in the spec the fields defined on Subscription wouldn't themselves be called subscriptions, similar to how fields on Query aren't queries. These are root fields that get used in subscription (respectively query) operations. I realize referring to these as root fields makes this overly technical, and because subscription operations can only include a single root field there is a one to one correspondence. So not sure if we need to be struct about terminology here.
There was a problem hiding this comment.
Yeah totally, I'll work on this. Also I wasn't aware sub operations can only have one root field! Makes a lot of sense.
docs/source/data/subscriptions.mdx
Outdated
| }; | ||
| ``` | ||
|
|
||
| The `subscribe` function must return an object of type `AsyncIterable`, part of Apollo Server's pub/sub API (described below). |
There was a problem hiding this comment.
AsyncIterable isn't really part of Apollo Server's API, but defined in ES2018. Maybe we could mention that it's a standard JavaScript API that is used to return a stream of asynchronous results, and that that is the only required API surface, but that Apollo Server includes a PubSub class as a convenience to implement an event bus.
docs/source/data/subscriptions.mdx
Outdated
| * The first parameter is the name of the event label you're publishing to, as a string. | ||
| * _You don't need to register a label name before publishing to it._ | ||
| * The second parameter is the payload associated with the event. | ||
| * _The payload's structure should match the structure that clients expect from the associated subscription's return type._ |
There was a problem hiding this comment.
It doesn't have to match the structure client's expect though. It's the task of the resolver to map between events and results (what is described as MapSourceToResponseEvent in the spec).
docs/source/data/subscriptions.mdx
Outdated
| * The second parameter is the payload associated with the event. | ||
| * _The payload's structure should match the structure that clients expect from the associated subscription's return type._ | ||
|
|
||
| When working with GraphQL subscriptions, you `publish` an event whenever a subscription's return value should be updated. One of the most common causes of such an update is a mutation. |
There was a problem hiding this comment.
Maybe add that these events don't have to be triggered as a result of GraphQL operations, but can also connect to an existing event bus and be triggered by other systems.
StephenBarlow
force-pushed
the
sb/subscriptions-edits
branch
from
6be94b7 to
7563e3d
Compare
StephenBarlow
force-pushed
the
sb/subscriptions-edits
branch
from
ca6e9cd to
1b0b122
Compare
StephenBarlow
force-pushed
the
sb/subscriptions-edits
branch
from
1b0b122 to
3528236
Compare
No description provided.