GraphQL Service

Last updated 4 days ago


Realm Object Server offers a web API through GraphQL. This enables retrieving Realm data in a web browser or in other backend language environments unsupported with Realm SDKs currently. The GraphQL API is provided through an additional service that can be run within the Realm Object Server alongside the default services (sync, authentication, etc) or it can be run within another Realm Object Server standalone.

The GraphQL service supports query and mutation via standard HTTP requests and realtime subscription events via a websocket connection.

Setup GraphQL Service

To setup the GraphQL service you will need to either integrate it into an existing Realm Object Server project, or create another one specifically for the GraphQL service by running ros init:

ros init ros-graphql

The service is enabled by default. If you need to make any modifications, /src/index.ts file and edit it:

import { BasicServer } from 'realm-object-server'
import * as path from 'path'
import { GraphQLService } from 'realm-graphql-service'
const server = new BasicServer()
// Server configs...
graphQLServiceConfigOverride: (config) => {
// Turn this off in production!
config.disableAuthentication = true
}).then(() => {
console.log(`Realm Object Server was started on ${server.address}`)
}).catch(err => {
console.error(`Error starting Realm Object Server: ${err.message}`)

Start the server with your GraphQL service:

npm start

You can verify that the service is running by opening up:http://localhost:9080/graphql/explore/%2F__admin which displays GraphiQL, the in-browser IDE for exploring GraphQL. This url connects to your admin realm. Connect to a different realm like: http://localhost:9080/graphql/explore/<realm_path>

Configuring the service

The GraphQL service exposes various configuration options that allow you to change the behavior of the service. While we recommend the defaults for most use cases, you may need to adjust them to fit your schema or usage patterns. For a detailed overview of the customization options, refer to the GraphQL Service API Reference.

The GraphQL service on Realm Cloud is not configurable. We'll expose controls to configure it in the future.

  • disableAuthentication controls whether authentication should be enabled for both the GraphQL and GraphiQL Explorer endpoints. It can be useful to disable while developing to remove the overhead of dealing with access tokens.

  • forceExplorerSSL controls whether the GraphiQL explorer will use SSL to connect to the service. Typically, it will infer the correct protocol from the url scheme, but if you have a load balancer that terminates SSL, it may get confused.

  • includeCountInResponses controls the type of the collection response. If the count is included, an envelope response will be used, containing count and items properties. It is recommended to set this to true as it will become a default in a future version.

  • presentIntsAsFloatsInSchema controls whether integers in the schema will be presented as floats. GraphQL's integer type is 32 bit, which is smaller than javascript's number type. The benefit of enabling that is that it'll increase the range of returned values, at the cost of type safety.

  • Renaming system types: there are several properties controlling the names/suffixes of system types. If they collide with types, defined in your Realm, you'll get an error of the type "Invalid options provided to ApolloServer: Type "something" was defined more than once". To resolve that, identify the colliding model name and set the relevant property to rename it.

Best Practices

Require Authentication

During development, you may have disabled authentication to make working with the API simpler. Before moving into a production environment, always make sure that disableAuthentication is set to false

Run the Service from a Dedicated Node

For best results, we recommend running the GraphQL Service from its own node of your cluster for best performance. This can be done with our Kubernetes deployment.