Web-based App (GraphQL) Quick Start

We're going to show you how to call the GraphQL API from a basic Javascript client using a few helpers and convenience APIs for the Apollo Client, a popular Javascript client that supports a variety of web frameworks as well as Node.js

We are currently working on recreating our mobile ToDo app in the browser for a more complete Getting Started experience. For now, please follow this basic example below

Overview

Since the Realm database is an embedded database, it cannot be embedded directly into a user's browser. However, we recognize that our developers have product offerings that span both mobile and web applications. To solve this, Realm Platform offers a GraphQL API which enables retrieving Realm data in a web browser or in other backend language environments not currently supported by a Realm SDK. The GraphQL API supports retrieving data or applying changes via HTTP requests and realtime subscription events via a Websocket connection.

If you are working with the self-hosted version of Realm Platform, you will need to enable the GraphQL API on your Realm Object Server. More details here.

Getting Started with GraphQL

Prerequisites

  • Node v7.6.x or higher (we typically recommended the latest LTS)

  • A package manager like NPM

  • An IDE to work in (we typically recommend Visual Studio Code)

  • A cloud or self-hosted instance of the Realm Object Server which has the GraphQL Service enabled

Import your required libraries

We'll start by creating our typescript file. Mine is called index.tsWe'll then import the various libraries which we will use.

index.ts
import * as Realm from "realm";
import { Credentials, User, GraphQLConfig } from "realm-graphql-client";
import { concat, split } from "apollo-link";
import { fetch } from "cross-fetch";
import { HttpLink } from "apollo-link-http";
import { SubscriptionClient } from 'subscriptions-transport-ws';
import { WebSocketLink } from 'apollo-link-ws';
import * as ws from "ws";
import { getMainDefinition } from 'apollo-utilities';
import { InMemoryCache } from 'apollo-cache-inmemory'
import { ApolloClient } from 'apollo-client';
import gql from 'graphql-tag';
import * as constants from './constants';

Login to Realm Platform

Make sure that you've properly filled out the constants file which was created during our loader exercise.

index.ts
async function testGraphQL() {
const credentials = Credentials.usernamePassword(constants.username, constants.password);
const user = await User.authenticate(credentials, `https://${constants.serverUrl}`);
const config = await GraphQLConfig.create(
user,
'/default'
);
}

Setup your GraphQL Configuration

Next we'll setup our GraphQL Configuration using the Apollo Client

index.ts
function setupGraphQL(config: GraphQLConfig) {
const httpLink = concat(
config.authLink,
// Note: if using node.js, you'll need to provide fetch as well.
new HttpLink({ uri: config.httpEndpoint, fetch })
);
const webSocketLink = new WebSocketLink({
uri: config.webSocketEndpoint,
options: {
connectionParams: config.connectionParams,
},
webSocketImpl: ws
});
const link = split(({ query }) => {
const definition = getMainDefinition(query);
return definition.kind === 'OperationDefinition' && definition.operation === 'subscription';
},
webSocketLink,
httpLink);
return new ApolloClient({
link: link,
cache: new InMemoryCache()
});
}

Make a GraphQL Query

And finally, we'll perform a simple query that will print all of our tasks to the console. You can learn more about the various queries and mutations that you can make with GraphQL here.

Your finished script should look like the following:

index.ts
import * as Realm from "realm";
import { Credentials, User, GraphQLConfig } from "realm-graphql-client";
import { concat, split } from "apollo-link";
import { fetch } from "cross-fetch";
import { HttpLink } from "apollo-link-http";
import { SubscriptionClient } from 'subscriptions-transport-ws';
import { WebSocketLink } from 'apollo-link-ws';
import * as ws from "ws";
import { getMainDefinition } from 'apollo-utilities';
import { InMemoryCache } from 'apollo-cache-inmemory'
import { ApolloClient } from 'apollo-client';
import gql from 'graphql-tag';
import * as constants from './constants';
async function testGraphQL() {
const credentials = Credentials.usernamePassword(constants.username, constants.password);
const user = await User.authenticate(credentials, `https://${constants.serverUrl}`);
const config = await GraphQLConfig.create(
user,
'/default'
);
const client = setupGraphQL(config);
const response = await client.query({
query: gql`
query {
items {
itemId
body
}
}
`
});
console.log(response.data);
while (true) {
await new Promise(resolve => setTimeout(resolve, 500));
}
}
function setupGraphQL(config: GraphQLConfig) {
const httpLink = concat(
config.authLink,
// Note: if using node.js, you'll need to provide fetch as well.
new HttpLink({ uri: config.httpEndpoint, fetch })
);
const webSocketLink = new WebSocketLink({
uri: config.webSocketEndpoint,
options: {
connectionParams: config.connectionParams,
},
webSocketImpl: ws
});
const link = split(({ query }) => {
const definition = getMainDefinition(query);
return definition.kind === 'OperationDefinition' && definition.operation === 'subscription';
},
webSocketLink,
httpLink);
return new ApolloClient({
link: link,
cache: new InMemoryCache()
});
}
testGraphQL();