Playground API

Live GraphQL Subscription Studio

graphql-ws

Connect over RFC-compliant WebSocket transport and watch reactive data streams in real time.

Disconnected
Subscription Document (SDL)ws://.../graphql
Query Variables (JSON)
Simulate Live Mutation
POST /posts

Trigger a real database mutation in your session sandbox. The server will immediately publish an event through the GraphQL WebSocket connection.

Live Event Stream
0 events

No events captured yet.

Click “Connect & Subscribe” and trigger a mutation to observe real-time data flow.

WebSocket Architecture & graphql-ws Transport

Playground API provides stateful real-time GraphQL Subscriptions over WebSocket compliant with the modern graphql-ws protocol. Whenever a record is created or updated in your sandbox (via GraphQL mutations or REST endpoints), the reactive in-memory PubSub engine immediately publishes the event to active WebSocket listeners scoped strictly to your sandbox session.

RFC graphql-ws Protocol

Native compatibility with Apollo Client GraphQLWsLink, Urql, Relay, and modern GraphQL developer tooling.

Unified REST & GQL Mutations

Events are emitted regardless of whether mutations are made via REST (POST /posts) or GraphQL (createPost).

Session Sandbox Isolation

Subscription streams are scoped to your session identity token (token or Authorization: Bearer), preventing cross-user noise.

Supported Subscription Fields & Arguments

Subscription FieldArgumentsReturn TypeDescription
postAdded—Post!Fires when any new post is created in the current sandbox.
commentAddedpostId: IDComment!Fires when a comment is added, optionally filtered by postId.
todoUpdateduserId: IDTodo!Fires when a todo is created or updated in the current sandbox.
customRecordMutatedcollection: String!CustomRecord!Fires when a dynamic custom entity (e.g. products, orders) is mutated.

Client Integration Examples

Apollo Client 3 (GraphQLWsLink)

typescript
1
// 1. Apollo Client Setup with GraphQLWsLink & HttpLink
2
import { ApolloClient, InMemoryCache, split, HttpLink } from '@apollo/client';
3
import { GraphQLWsLink } from '@apollo/client/link/subscriptions';
4
import { createClient } from 'graphql-ws';
5
import { getMainDefinition } from '@apollo/client/utilities';
6
7
// HTTP Link for queries and mutations
8
const httpLink = new HttpLink({
9
uri: 'https://playground.nileslabs.com/api/v1/graphql',
10
headers: {
11
'X-Playground-Identity': 'your_sandbox_identity_token',
12
},
13
});
14
15
// WebSocket Link for live subscriptions
16
const wsLink = new GraphQLWsLink(
17
createClient({
18
url: '/graphql',
19
connectionParams: {
20
token: 'your_sandbox_identity_token',
21
},
22
})
23
);
24
25
// Split link based on operation type
26
const splitLink = split(
27
({ query }) => {
28
const definition = getMainDefinition(query);
29
return (
30
definition.kind === 'OperationDefinition' &&
31
definition.operation === 'subscription'
32
);
33
},
34
wsLink,
35
httpLink
36
);
37
38
export const client = new ApolloClient({
39
link: splitLink,
40
cache: new InMemoryCache(),
41
});

React useSubscription Hook Example

tsx
1
// 2. React Component using Apollo's useSubscription Hook
2
import React from 'react';
3
import { useSubscription, gql } from '@apollo/client';
4
5
const POST_ADDED_SUBSCRIPTION = gql
6
subscription OnPostAdded {
7
postAdded {
8
id
9
title
10
body
11
user {
12
name
13
email
14
}
15
}
16
}
17
;
18
19
export function LivePostFeed() {
20
const { data, loading, error } = useSubscription(POST_ADDED_SUBSCRIPTION);
21
22
if (loading) return <div>Listening for new posts over WebSocket...</div>;
23
if (error) return <div>Subscription Error: {error.message}</div>;
24
25
return (
26
<div className="p-4 rounded-xl border border-emerald-500 bg-emerald-50">
27
<h3 className="font-bold text-emerald-900">⚡ New Post Received Live!</h3>
28
<p className="font-semibold">{data?.postAdded?.title}</p>
29
<p className="text-sm text-slate-600">{data?.postAdded?.body}</p>
30
</div>
31
);
32
}

Urql Subscription Exchange

typescript
1
// 3. Urql Setup with Subscription Exchange
2
import { createClient, defaultExchanges, subscriptionExchange } from 'urql';
3
import { createClient as createWSClient } from 'graphql-ws';
4
5
const wsClient = createWSClient({
6
url: '/graphql',
7
connectionParams: {
8
token: 'your_sandbox_identity_token',
9
},
10
});
11
12
export const urqlClient = createClient({
13
url: 'https://playground.nileslabs.com/api/v1/graphql',
14
exchanges: [
15
...defaultExchanges,
16
subscriptionExchange({
17
forwardSubscription: (operation) => ({
18
subscribe: (sink) => ({
19
unsubscribe: wsClient.subscribe(operation, sink),
20
}),
21
}),
22
}),
23
],
24
});

Official TypeScript SDK

typescript
1
// 4. Official TypeScript SDK (Zero-Dependency Helper)
2
import { PlaygroundClient } from 'playground-api';
3
4
const client = new PlaygroundClient({
5
apiUrl: 'https://playground.nileslabs.com/api/v1',
6
identityToken: 'your_sandbox_identity_token',
7
});
8
9
// Subscribe to real-time post creation
10
const unsubscribe = client.gql.subscribe(
11
12
subscription {
13
postAdded {
14
id
15
title
16
}
17
}
18
,
19
{},
20
{
21
onNext: (data) => console.log('Live Post Received:', data),
22
onError: (err) => console.error('Subscription error:', err),
23
onComplete: () => console.log('Subscription completed'),
24
}
25
);
26
27
// To cancel subscription later:
28
// unsubscribe();
PreviousGraphiQL IDE & Explorer
NextPosts GraphQL Schema