Atlas GraphQL API
On this page
You can query your data in MongoDB Atlas from your client app using the Atlas GraphQL API and the Realm Flutter SDK. You can use any standard GraphQL client to query the Atlas GraphQL API.
Prerequisites
Set Up GraphQL Client
Get Your App ID and GraphQL Endpoint
Once you've completed the all the necessary actions in the Prerequisites section above, you must find your App ID and GraphQL endpoint.
You can find both of these in your App's UI on Atlas:
To find your App ID, refer to Find Your App ID.
To find your GraphQL Endpoint in the Atlas UI, navigate to the GraphQL page. Near the top of the page, you can copy the GraphQL Endpoint link.
Install a GraphQL Client Package
Install a standard GraphQL client. This page uses graphql, a lightweight GraphQL client that you can use in Dart standalone and Flutter apps.
flutter pub add graphql
If you haven't already installed the Realm SDK, you can do so now as well.
flutter pub add realm
While the examples on this page use graphql to query the Atlas GraphQL API,
there are other Dart and Flutter GraphQL packages that you could use.
For example, the graphql_flutter
package includes Flutter widget wrappers around the graphql library
to provide a more idiomatic Flutter development experience and reduce
the need for writing boilerplate code.
Import dependencies
Import the realm and graphql packages into your Flutter app.
This example also imports the dart:async library to help refresh
the access token used in the GraphQL queries.
import 'package:graphql/client.dart'; import 'package:realm/realm.dart'; import "dart:async"; // used to refresh access token
Instantiate an App Services Client & Log In a User
Instantiate the App Services client to connect to the backend.
You must log a user in to the App client to authenticate requests
to the Atlas GraphQL API with the user's access token.
This example also invokes Timer.periodic() to refresh the access token
in the background. The access token doesn't refresh automatically.
final app = App(AppConfiguration(YOUR_APP_ID)); await app.logIn(Credentials.anonymous()); // Refresh the user access token every 29 minutes, as the default expiration // time for an access token is 30 minutes. Timer.periodic( Duration(minutes: 29), (_) => app.currentUser?.refreshCustomData());
Instantiate a GraphQL Client
Now you can use the logged in user's accessToken
property to authenticate with the Atlas GraphQL API.
To query the GraphQL API as a user, use Bearer token authentication
with the user's accessToken.
Use the graphql package to create a GraphQL client to run queries from.
// Build GraphQL endpoint and client // In the `authLink`, retrieve the accessToken from the app's // currently logged in user on each request. // If there's no logged in user, pass an empty string as Bearer token, // causing the request to fail. final authLink = AuthLink( getToken: () => 'Bearer ${app.currentUser?.accessToken ?? ""}', ); final link = authLink.concat(HttpLink(YOUR_GRAPHQL_URL)); final client = GraphQLClient(link: link, cache: GraphQLCache());
To learn more about the ways to authenticate requests to the Atlas GraphQL API, refer to Authenticate GraphQL Requests in the App Services documentation.
Run Queries and Mutations
Run queries and mutations with the Atlas GraphQL API from the client.
To learn more about available operations, refer to the following App Services documentation:
You can also find your entire schema and explore it with test operations in the GraphQL section of the App Services UI.
Run a Query
You can query the Atlas GraphQL API schema with query resolvers generated when you define your schema. To learn more about the generated queries and the inputs they accept, refer to Query Resolvers in the App Services documentation.
final query = """ query { plants(limit: 5) { _id name color } } """; final queryOptions = QueryOptions( document: gql(query), ); final queryRes = await client.query(queryOptions);
Run a Mutation
You can run mutation against the Atlas GraphQL API schema with mutation resolvers generated when you define your schema. To learn more about the generated mutations and the inputs they accept, refer to Mutation Resolvers in the App Services documentation.
final mutation = """ mutation AddPlant( \$_id: ObjectId!, \$name: String!, \$color: String) { insertOnePlant(data: { _id: \$_id name: \$name color: \$color }) { _id name color } } """; final mutationOptions = MutationOptions( document: gql(mutation), variables: { '_id': ObjectId().toString(), 'name': 'lily', 'color': 'white' }); final mutationRes = await client.mutate(mutationOptions);