Commit 4317bf91 authored by Vitaly Slobodin's avatar Vitaly Slobodin

Merge branch 'ntepluhina-subscriptions-docs' into 'master'

Add GraphQL subscriptions to frontend guidelines

See merge request gitlab-org/gitlab!64190
parents cd4b8d4c fdff4cbd
......@@ -842,6 +842,70 @@ Keep in mind, this means your app will not batch queries.
Once subscriptions are mature, this process can be replaced by using them and we can remove the separate link library and return to batching queries.
#### Subscriptions
We use [subscriptions](https://www.apollographql.com/docs/react/data/subscriptions/) to receive real-time updates from GraphQL API via websockets. Currently, the number of existing subscriptions is limited, you can check a list of available ones in [GraphqiQL explorer](https://gitlab.com/-/graphql-explorer)
**NOTE:**
We cannot test subscriptions using GraphiQL, because they require an ActionCable client, which GraphiQL does not support at the moment.
Subscriptions don't require any additional configuration of Apollo Client instance, you can use them in the application right away. To distinguish subscriptions from queries and mutations, we recommend naming them with `.subscription.graphql` extension:
```graphql
// ~/sidebar/queries/issuable_assignees.subscription.graphql
subscription issuableAssigneesUpdated($issuableId: IssuableID!) {
issuableAssigneesUpdated(issuableId: $issuableId) {
... on Issue {
assignees {
nodes {
...User
status {
availability
}
}
}
}
}
}
```
When using GraphQL subscriptions in Vue application, we recommend updating existing Apollo query results with [subscribeToMore](https://apollo.vuejs.org/guide/apollo/subscriptions.html#subscribe-to-more) option:
```javascript
import issuableAssigneesSubscription from '~/sidebar/queries/issuable_assignees.subscription.graphql'
apollo: {
issuable: {
query() {
return assigneesQueries[this.issuableType].query;
},
subscribeToMore: {
// Specify the subscription that will update the query
document() {
return issuableAssigneesSubscription;
},
variables() {
return {
issuableId: convertToGraphQLId(this.issuableClass, this.issuableId),
};
},
// Describe how subscription should update the query
updateQuery(prev, { subscriptionData }) {
if (prev && subscriptionData?.data?.issuableAssigneesUpdated) {
const data = produce(prev, (draftData) => {
draftData.workspace.issuable.assignees.nodes =
subscriptionData.data.issuableAssigneesUpdated.assignees.nodes;
});
return data;
}
return prev;
},
},
},
},
```
### Testing
#### Generating the GraphQL schema
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment