.svg)
.svg)
Thinking about using GraphQL but unsure where to start?
This is a concise tutorial based on our experience using GraphQL. You will learn how to use GraphQL in a Flutter app, including how to create a query, a mutation, and a subscription using the graphql_flutter plugin. Once you've mastered the fundamentals, you can move on to designing your own workflow.
Key topics and takeaways:
* GraphQL
* What is graphql_flutter?
* Setting up graphql_flutter and GraphQLProvider
* Queries
* Mutations
* Subscriptions
Looking to call multiple endpoints to populate data for a single screen? Wish you had more control over the data returned by the endpoint? Is it possible to get more data with a single endpoint call, or does the call only return the necessary data fields?
Follow along to learn how to do this with GraphQL. GraphQL’s goal was to change the way data is supplied from the backend, and it allows you to specify the data structure you want.
Let's imagine that we have the table model in our database that looks like this:
Movie {
title
genre
rating
year
}
These fields represent the properties of the Movie Model:
We can get movies like this using REST:
| /GET localhost:8080/movies |
| [ | |
| { | |
| "title": "The Godfather", | |
| "genre": "Drama", | |
| "rating": 9.2, | |
| "year": 1972 | |
| } | |
| ] |
As you can see, whether or not we need them, REST returns all of the properties of each movie. In our frontend, we may just need the title and genre properties, yet all of them were returned.
We can avoid redundancy by using GraphQL. We can specify the properties we wish to be returned using GraphQL, for example:
| query movies { Movie { title genre }} |
We're informing the server that we only require the movie table's title and genre properties. It provides us with exactly what we require:
| { | |
| "data": [ | |
| { | |
| "title": "The Godfather", | |
| "genre": "Drama" | |
| } | |
| ] | |
| } |
GraphQL is a backend technology, whereas Flutter is a frontend SDK for developing mobile apps. We get the data displayed on the mobile app from a backend when we use mobile apps.
It's simple to create a Flutter app that retrieves data from a GraphQL backend. Simply make an HTTP request from the Flutter app, then use the returned data to set up and display the UI.
The new graphql_flutter plugin includes APIs and widgets for retrieving and using data from GraphQL backends.
The new graphql_flutter plugin includes APIs and widgets that make it simple to retrieve and use data from a GraphQL backend.
graphql_flutter, as the name suggests, is a GraphQL client for Flutter. It exports widgets and providers for retrieving data from GraphQL backends, such as:
Create a Flutter project:
| flutter create flutter_graphqlcd flutter_graphql |
Next, install the graphql_flutter package:
| flutter pub add graphql_flutter |
The code above will set up the graphql_flutter package. This will include the graphql_flutter package in the dependencies section of your pubspec.yaml file:
| dependencies:graphql_flutter: ^5.0.0 |
To use the widgets, we must import the package as follows:
| import 'package:graphql_flutter/graphql_flutter.dart'; |
Before we can start making GraphQL queries and mutations, we must first wrap our root widget in GraphQLProvider. A GraphQLClient instance must be provided to the GraphQLProvider's client property.
| GraphQLProvider( client: GraphQLClient(...)) |
The GraphQLClient includes the GraphQL server URL as well as a caching mechanism.
| final httpLink = HttpLink(uri: "http://10.0.2.2:8000/");ValueNotifier<GraphQLClient> client = ValueNotifier( GraphQLClient( cache: InMemoryCache(), link: httpLink )); |
HttpLink is used to generate the URL for the GraphQL server. The GraphQLClient receives the instance of the HttpLink in the form of a link property, which contains the URL of the GraphQL endpoint.
The cache passed to GraphQLClient specifies the cache mechanism to be used. To persist or store caches, the InMemoryCache instance makes use of an in-memory database.
A GraphQLClient instance is passed to a ValueNotifier. This ValueNotifer holds a single value and has listeners that notify it when that value changes. This is used by graphql_flutter to notify its widgets when the data from a GraphQL endpoint changes, which helps graphql_flutter remain responsive.
We'll now encase our MaterialApp widget in GraphQLProvider:
| void main() { runApp(MyApp());}class MyApp extends StatelessWidget { // This widget is the root of your application. @override Widget build(BuildContext context) { return GraphQLProvider( client: client, child: MaterialApp( title: 'GraphQL Demo', theme: ThemeData(primarySwatch: Colors.blue), home: MyHomePage(title: 'GraphQL Demo'), )); }} |
We'll use the Query widget to create a query with the graphql_flutter package.
| class MyHomePage extends StatelessWidget { @override Widget build(BuildContext) { return Query( options: QueryOptions( document: gql(readCounters), variables: { 'counterId': 23, }, pollInterval: Duration(seconds: 10), ), builder: (QueryResult result, { VoidCallback refetch, FetchMore fetchMore }) { if (result.hasException) { return Text(result.exception.toString()); } if (result.isLoading) { return Text('Loading'); } // it can be either Map or List List counters = result.data['counter']; return ListView.builder( itemCount: repositories.length, itemBuilder: (context, index) { return Text(counters\[index\]['name']); }); },) }} |
The Query widget encloses the ListView widget, which will display the list of counters to be retrieved from our GraphQL server. As a result, the Query widget must wrap the widget where the data fetched by the Query widget is to be displayed.
The Query widget cannot be the tree's topmost widget. It can be placed wherever you want as long as the widget that will use its data is underneath or wrapped by it.
In addition, two properties have been passed to the Query widget: options and builder.
options
| options: QueryOptions( document: gql(readCounters), variables: { 'conuterId': 23, }, pollInterval: Duration(seconds: 10),), |
The option property is where the query configuration is passed to the Query widget. This options prop is a QueryOptions instance. The QueryOptions class exposes properties that we use to configure the Query widget.
The query string or the query to be conducted by the Query widget is set or sent in via the document property. We passed in the readCounters string here:
| final String readCounters = """query readCounters(\$counterId: Int!) { counter { name id }}"""; |
The variables attribute is used to send query variables to the Query widget. There is a 'counterId': 23 there. In the readCounters query string, this will be passed in place of $counterId.
The pollInterval specifies how often the Query widget polls or refreshes the query data. The timer is set to 10 seconds, so the Query widget will perform HTTP requests to refresh the query data every 10 seconds.
builder
A function is the builder property. When the Query widget sends an HTTP request to the GraphQL server endpoint, this function is called. The Query widget calls the builder function with the data from the query, a function to re-fetch the data, and a function for pagination. This is used to get more information.
The builder function returns widgets that are listed below the Query widget. The result argument is a QueryResult instance. The QueryResult class has properties that can be used to determine the query's current state and the data returned by the Query widget.
Let's look at how to make mutation queries with the Mutation widget in graphql_flutter.
The Mutation widget is used as follows:
| Mutation( options: MutationOptions( document: gql(addCounter), update: (GraphQLDataProxy cache, QueryResult result) { return cache; }, onCompleted: (dynamic resultData) { print(resultData); }, ), builder: ( RunMutation runMutation, QueryResult result, ) { return FlatButton( onPressed: () => runMutation({ 'counterId': 21, }), child: Text('Add Counter')); },); |
The Mutation widget, like the Query widget, accepts some properties.
When the Mutation's mutation is finished, the builder is called, and the Mutation rebuilds its tree. runMutation and the mutation result are passed to the builder function.
Subscriptions in GraphQL are similar to an event system that listens on a WebSocket and calls a function whenever an event is emitted into the stream.
The client connects to the GraphQL server via a WebSocket. The event is passed to the WebSocket whenever the server emits an event from its end. So this is happening in real-time.
The graphql_flutter plugin in Flutter uses WebSockets and Dart streams to open and receive real-time updates from the server.
Let's look at how we can use our Flutter app's Subscription widget to create a real-time connection. We'll start by creating our subscription string:
| final counterSubscription = '''subscription counterAdded { counterAdded { name id }}'''; |
When we add a new counter to our GraphQL server, this subscription will notify us in real-time.
| Subscription( options: SubscriptionOptions( document: gql(counterSubscription), ), builder: (result) { if (result.hasException) { return Text("Error occurred: " + result.exception.toString()); } if (result.isLoading) { return Center( child: const CircularProgressIndicator(), ); } return ResultAccumulator.appendUniqueEntries( latest: result.data, builder: (context, {results}) => ... ); }), |
The Subscription widget has several properties, as we can see:
The subscription result is used to call the builder function. The end result has the following properties:
The provided helper widget ResultAccumulator is used to collect subscription results, according to graphql_flutter's pub.dev page.
This blog intends to help you understand what makes GraphQL so powerful, how to use it in Flutter, and how to take advantage of the reactive nature of graphql_flutter. You can now take the first steps in building your applications with GraphQL!
Did you like the blog? If yes, we're sure you'll also like to work with the people who write them - our best-in-class engineering team.
We're looking for talented developers who are passionate about new emerging technologies. If that's you, get in touch with us.
Thinking about using GraphQL but unsure where to start?
This is a concise tutorial based on our experience using GraphQL. You will learn how to use GraphQL in a Flutter app, including how to create a query, a mutation, and a subscription using the graphql_flutter plugin. Once you've mastered the fundamentals, you can move on to designing your own workflow.
Key topics and takeaways:
* GraphQL
* What is graphql_flutter?
* Setting up graphql_flutter and GraphQLProvider
* Queries
* Mutations
* Subscriptions
Looking to call multiple endpoints to populate data for a single screen? Wish you had more control over the data returned by the endpoint? Is it possible to get more data with a single endpoint call, or does the call only return the necessary data fields?
Follow along to learn how to do this with GraphQL. GraphQL’s goal was to change the way data is supplied from the backend, and it allows you to specify the data structure you want.
Let's imagine that we have the table model in our database that looks like this:
Movie {
title
genre
rating
year
}
These fields represent the properties of the Movie Model:
We can get movies like this using REST:
| /GET localhost:8080/movies |
| [ | |
| { | |
| "title": "The Godfather", | |
| "genre": "Drama", | |
| "rating": 9.2, | |
| "year": 1972 | |
| } | |
| ] |
As you can see, whether or not we need them, REST returns all of the properties of each movie. In our frontend, we may just need the title and genre properties, yet all of them were returned.
We can avoid redundancy by using GraphQL. We can specify the properties we wish to be returned using GraphQL, for example:
| query movies { Movie { title genre }} |
We're informing the server that we only require the movie table's title and genre properties. It provides us with exactly what we require:
| { | |
| "data": [ | |
| { | |
| "title": "The Godfather", | |
| "genre": "Drama" | |
| } | |
| ] | |
| } |
GraphQL is a backend technology, whereas Flutter is a frontend SDK for developing mobile apps. We get the data displayed on the mobile app from a backend when we use mobile apps.
It's simple to create a Flutter app that retrieves data from a GraphQL backend. Simply make an HTTP request from the Flutter app, then use the returned data to set up and display the UI.
The new graphql_flutter plugin includes APIs and widgets for retrieving and using data from GraphQL backends.
The new graphql_flutter plugin includes APIs and widgets that make it simple to retrieve and use data from a GraphQL backend.
graphql_flutter, as the name suggests, is a GraphQL client for Flutter. It exports widgets and providers for retrieving data from GraphQL backends, such as:
Create a Flutter project:
| flutter create flutter_graphqlcd flutter_graphql |
Next, install the graphql_flutter package:
| flutter pub add graphql_flutter |
The code above will set up the graphql_flutter package. This will include the graphql_flutter package in the dependencies section of your pubspec.yaml file:
| dependencies:graphql_flutter: ^5.0.0 |
To use the widgets, we must import the package as follows:
| import 'package:graphql_flutter/graphql_flutter.dart'; |
Before we can start making GraphQL queries and mutations, we must first wrap our root widget in GraphQLProvider. A GraphQLClient instance must be provided to the GraphQLProvider's client property.
| GraphQLProvider( client: GraphQLClient(...)) |
The GraphQLClient includes the GraphQL server URL as well as a caching mechanism.
| final httpLink = HttpLink(uri: "http://10.0.2.2:8000/");ValueNotifier<GraphQLClient> client = ValueNotifier( GraphQLClient( cache: InMemoryCache(), link: httpLink )); |
HttpLink is used to generate the URL for the GraphQL server. The GraphQLClient receives the instance of the HttpLink in the form of a link property, which contains the URL of the GraphQL endpoint.
The cache passed to GraphQLClient specifies the cache mechanism to be used. To persist or store caches, the InMemoryCache instance makes use of an in-memory database.
A GraphQLClient instance is passed to a ValueNotifier. This ValueNotifer holds a single value and has listeners that notify it when that value changes. This is used by graphql_flutter to notify its widgets when the data from a GraphQL endpoint changes, which helps graphql_flutter remain responsive.
We'll now encase our MaterialApp widget in GraphQLProvider:
| void main() { runApp(MyApp());}class MyApp extends StatelessWidget { // This widget is the root of your application. @override Widget build(BuildContext context) { return GraphQLProvider( client: client, child: MaterialApp( title: 'GraphQL Demo', theme: ThemeData(primarySwatch: Colors.blue), home: MyHomePage(title: 'GraphQL Demo'), )); }} |
We'll use the Query widget to create a query with the graphql_flutter package.
| class MyHomePage extends StatelessWidget { @override Widget build(BuildContext) { return Query( options: QueryOptions( document: gql(readCounters), variables: { 'counterId': 23, }, pollInterval: Duration(seconds: 10), ), builder: (QueryResult result, { VoidCallback refetch, FetchMore fetchMore }) { if (result.hasException) { return Text(result.exception.toString()); } if (result.isLoading) { return Text('Loading'); } // it can be either Map or List List counters = result.data['counter']; return ListView.builder( itemCount: repositories.length, itemBuilder: (context, index) { return Text(counters\[index\]['name']); }); },) }} |
The Query widget encloses the ListView widget, which will display the list of counters to be retrieved from our GraphQL server. As a result, the Query widget must wrap the widget where the data fetched by the Query widget is to be displayed.
The Query widget cannot be the tree's topmost widget. It can be placed wherever you want as long as the widget that will use its data is underneath or wrapped by it.
In addition, two properties have been passed to the Query widget: options and builder.
options
| options: QueryOptions( document: gql(readCounters), variables: { 'conuterId': 23, }, pollInterval: Duration(seconds: 10),), |
The option property is where the query configuration is passed to the Query widget. This options prop is a QueryOptions instance. The QueryOptions class exposes properties that we use to configure the Query widget.
The query string or the query to be conducted by the Query widget is set or sent in via the document property. We passed in the readCounters string here:
| final String readCounters = """query readCounters(\$counterId: Int!) { counter { name id }}"""; |
The variables attribute is used to send query variables to the Query widget. There is a 'counterId': 23 there. In the readCounters query string, this will be passed in place of $counterId.
The pollInterval specifies how often the Query widget polls or refreshes the query data. The timer is set to 10 seconds, so the Query widget will perform HTTP requests to refresh the query data every 10 seconds.
builder
A function is the builder property. When the Query widget sends an HTTP request to the GraphQL server endpoint, this function is called. The Query widget calls the builder function with the data from the query, a function to re-fetch the data, and a function for pagination. This is used to get more information.
The builder function returns widgets that are listed below the Query widget. The result argument is a QueryResult instance. The QueryResult class has properties that can be used to determine the query's current state and the data returned by the Query widget.
Let's look at how to make mutation queries with the Mutation widget in graphql_flutter.
The Mutation widget is used as follows:
| Mutation( options: MutationOptions( document: gql(addCounter), update: (GraphQLDataProxy cache, QueryResult result) { return cache; }, onCompleted: (dynamic resultData) { print(resultData); }, ), builder: ( RunMutation runMutation, QueryResult result, ) { return FlatButton( onPressed: () => runMutation({ 'counterId': 21, }), child: Text('Add Counter')); },); |
The Mutation widget, like the Query widget, accepts some properties.
When the Mutation's mutation is finished, the builder is called, and the Mutation rebuilds its tree. runMutation and the mutation result are passed to the builder function.
Subscriptions in GraphQL are similar to an event system that listens on a WebSocket and calls a function whenever an event is emitted into the stream.
The client connects to the GraphQL server via a WebSocket. The event is passed to the WebSocket whenever the server emits an event from its end. So this is happening in real-time.
The graphql_flutter plugin in Flutter uses WebSockets and Dart streams to open and receive real-time updates from the server.
Let's look at how we can use our Flutter app's Subscription widget to create a real-time connection. We'll start by creating our subscription string:
| final counterSubscription = '''subscription counterAdded { counterAdded { name id }}'''; |
When we add a new counter to our GraphQL server, this subscription will notify us in real-time.
| Subscription( options: SubscriptionOptions( document: gql(counterSubscription), ), builder: (result) { if (result.hasException) { return Text("Error occurred: " + result.exception.toString()); } if (result.isLoading) { return Center( child: const CircularProgressIndicator(), ); } return ResultAccumulator.appendUniqueEntries( latest: result.data, builder: (context, {results}) => ... ); }), |
The Subscription widget has several properties, as we can see:
The subscription result is used to call the builder function. The end result has the following properties:
The provided helper widget ResultAccumulator is used to collect subscription results, according to graphql_flutter's pub.dev page.
This blog intends to help you understand what makes GraphQL so powerful, how to use it in Flutter, and how to take advantage of the reactive nature of graphql_flutter. You can now take the first steps in building your applications with GraphQL!
.svg)
.svg)
.png)
