GraphQL - freeCodeCamp.org

How to Use GraphQL in Flutter: A Handbook for Developers

Atuoha Anthony — Mon, 06 Apr 2026 14:12:17 +0000

There's a moment that most Flutter developers experience at some point in their careers.

You're building a screen that needs a user's name, their latest five posts, and the like count on each post. Seems simple enough. You make a request to /users/42, and the server sends back twenty fields you didn't ask for.

You make another request to /users/42/posts, and again the server sends back everything it knows about those posts, including fields your UI will never display.

Then you realize you also need the comment count per post, so you loop through the posts and fire five more requests, one per post.

By the time the screen loads, your Flutter app has made seven network requests, downloaded kilobytes of data it immediately discarded, and your users on slower networks are staring at a spinner, wondering if the app is broken.

This isn't a rare edge case. This is the everyday reality of building complex UIs on top of conventional REST APIs, and every developer who has shipped a serious mobile app has felt this friction.

The data you need and the data the API gives you are almost never a perfect match. You either get too much or not enough, and the cost is measured in wasted bandwidth, slower screens, more complex client-side code, and frustrated users.

GraphQL was invented to solve exactly this. Not theoretically, not as an academic exercise, but because the engineers at Facebook in 2012 were building a News Feed that needed data from dozens of resources simultaneously, on mobile devices running on 2G networks, and the REST approach was simply not good enough.

Their answer was to give the client full control over the shape of the data it receives. Instead of the server deciding what you get, you tell the server exactly what you need and it gives you precisely that, in one trip.

This handbook is a complete, engineering-depth guide to understanding GraphQL from first principles and using it confidently inside Flutter applications with the graphql_flutter package.

You won't just learn what the APIs look like. You'll understand why the library is designed the way it is, how the pieces fit together architecturally, what the normalized cache does and why it matters, and how to structure a real production app around GraphQL so that it stays maintainable as it grows.

By the end, you'll be able to build real-world Flutter apps backed by GraphQL. You'll also be able to reason clearly about when GraphQL is and is not the right tool and avoid the pitfalls that trip up most developers making this transition for the first time.

Prerequisites
What is GraphQL?
- Why Facebook Built It
Understanding the Problem: Life Before GraphQL
The Single Endpoint Approach
- One Endpoint, Client-Defined Data
- Why GraphQL Doesn't Need Versioning
Core GraphQL Concepts: A Deep Dive
GraphQL Architecture in Flutter
- How the Pieces Connect
- The Normalized Cache: GraphQL's Secret Weapon
Setting Up GraphQL in Flutter
Using GraphQL in Flutter: Queries, Mutations, and Subscriptions
Advanced Concepts
Best Practices in Real Apps
When to Use GraphQL and When Not To
- Where GraphQL Excels
- Where GraphQL is the Wrong Choice
Common Mistakes
Mini End-to-End Example
Conclusion
References

Prerequisites

Before diving into GraphQL and graphql_flutter, you should be comfortable with a few foundational areas. This guide doesn't assume you're an expert in any of them, but it builds on these skills throughout.

Flutter and Dart fundamentals. You should be able to build a multi-screen Flutter app with StatefulWidget and StatelessWidget. Understanding widget trees, BuildContext, setState, and Dart's async/await model is essential. If you have built a weather app or a to-do list app in Flutter, you have everything you need to follow along.
HTTP and APIs. You should understand what an API is, what an HTTP request is, and how JSON flows between a client and a server. You don't need to know the internals of HTTP, but knowing that a client sends a request and a server responds with structured data is the baseline assumption this guide builds on.
Basic state management. Familiarity with at least one state management approach such as Provider, Bloc, or Riverpod will help you understand the architecture discussions in later sections. You can follow the guide without it, but those sections will make more sense if you have seen how Flutter apps separate UI from business logic.
Tools for the project. Make sure your development environment includes the following before you begin:
- Flutter SDK 3.x or higher
- A code editor such as VS Code or Android Studio
- The flutter and dart CLIs accessible from your terminal
- An Android emulator, iOS simulator, or physical device for testing
Java 17 for Android builds. Because graphql_flutter ^5.3.0 requires Java 17 for Android, you need to confirm your JDK version before adding the package. Run java -version in your terminal and verify the output shows version 17. If not, install JDK 17 before proceeding. Android builds will fail with confusing errors if this requirement is not met.
Packages this guide uses. Your pubspec.yaml will include:

dependencies:
  flutter:
    sdk: flutter
  graphql_flutter: ^5.3.0
  flutter_hooks: ^0.20.0

The flutter_hooks dependency is needed only if you want to use the hooks-based API (useQuery, useMutation). This guide covers both the widget-based and hooks-based styles side by side.

What is GraphQL?

Imagine two restaurants. In the first restaurant, you sit down and the waiter brings you a fixed platter. The kitchen decides what goes on it: a burger, fries, a side salad, and a drink. You wanted just the burger with ketchup, but that's not how this restaurant works. You take the whole platter or you leave. If you also want dessert, you have to flag the waiter down for a second trip.

In the second restaurant, the waiter hands you a blank piece of paper. You write exactly what you want: one burger patty on a toasted bun, only ketchup, and a chocolate lava cake alongside it. You hand the note to the kitchen, and they bring you precisely that in one trip. No waste. No second journey.

The first restaurant is a REST API. The second is GraphQL.

That analogy captures the core idea well, but there's more depth to it. The blank piece of paper in the second restaurant isn't unlimited freedom. The kitchen still has a menu of ingredients they know how to prepare. You can only request things that exist in their kitchen.

In GraphQL terms, that menu of available ingredients is called the schema, and it's the formal contract between the server and every client that talks to it.

GraphQL is a query language for APIs and a runtime for executing those queries against your data. It was created by Facebook (now Meta) in 2012 and open-sourced in 2015. Unlike REST, which maps operations to specific URLs and HTTP verbs, GraphQL exposes a single endpoint where every operation is sent as a structured document in the request body.

The critical shift is this: in REST, the server decides what data you get. In GraphQL, the client decides. The server exposes a schema describing everything that's available. The client sends a query describing exactly what subset of that data it needs. The server resolves the query and returns precisely that shape – nothing added, nothing withheld.

Here's a simple GraphQL query:

query GetUser($userId: ID!) {
  user(id: $userId) {
    id
    name
    profilePic
  }
}

And the response:

{
  "data": {
    "user": {
      "id": "42",
      "name": "Atuoha Anthony",
      "profilePic": "https://cdn.example.com/atuoha.jpg"
    }
  }
}

The server didn't include email, createdAt, followersCount, or any other field it stores. It returned exactly and only what the query asked for.

Why Facebook Built It

GraphQL was created to solve three specific, well-documented pain points at Facebook in 2012. Understanding these problems in concrete terms matters because they're the same problems you've likely already encountered in your own apps.

The first problem was too many network requests. The Facebook News Feed required data from dozens of resources: posts, comments, likes, profiles, media attachments, and advertisements. With REST, each resource lived at a different endpoint, and assembling a single screen required hitting many of them, either sequentially (slow) or in parallel with complex client-side merging logic (also slow and fragile to maintain).

The second problem was data bloat. REST endpoints returned fixed response shapes defined by the server. The mobile client received everything the server thought might be useful, but mobile apps on 2G and 3G networks in 2012 couldn't afford to download kilobytes of fields that would never be displayed. Wasted bytes meant slower load times, higher data bills for users, and faster battery drain on their devices.

The third problem was API evolution velocity. Every time the News Feed team wanted to show a new piece of information, they either had to modify an existing API endpoint (risking breakage for other clients) or create a new one (bloating the API surface and creating versioning debt). The server and client were too tightly coupled, and every product iteration required a backend change to precede it.

GraphQL solved all three problems simultaneously: one request for any combination of data, client-defined field selection to eliminate waste, and schema evolution without endpoint versioning.

When Facebook open-sourced it in 2015, the broader developer community recognized immediately that these were not Facebook-specific problems. They were universal API problems, and GraphQL was a universal solution.

Understanding the Problem: Life Before GraphQL

How REST Works

REST (Representational State Transfer) is the architectural style that dominated API design for the better part of a decade and remains the most common approach in the industry today.

The core idea is straightforward: every resource lives at a specific URL called an endpoint. You interact with it using HTTP verbs: GET to read, POST to create, PUT or PATCH to update, and DELETE to remove.

For a typical social app, the REST API might look like this:

GET  /users/42            -- fetch user #42
GET  /users/42/posts      -- fetch posts by user #42
GET  /posts/17/comments   -- fetch comments on post #17
POST /posts               -- create a new post

Each endpoint has a fixed response shape defined by the server. When you call GET /users/42, you always receive the same fields regardless of which screen you are building or what data you actually need in that moment.

This works. For many applications and many teams, it works well. But it carries structural limitations that become increasingly painful as the application and its data requirements grow in complexity.

Over-fetching: Too Much Data

Over-fetching happens when the API returns more data than the client needs for a given screen. Your profile screen needs a user's name and profile picture, but the server sends fifteen fields.

On a desktop with a fast connection, the extra bytes barely register. On a mobile device on a congested network, they add latency, drain the battery faster, and cost users on metered data plans real money.

Multiply this across every API call in a complex app, and the cumulative waste becomes a meaningful performance problem.

Under-fetching: Not Enough Data

Under-fetching is the opposite. A single endpoint doesn't return enough data for a screen, so the client must make multiple requests to assemble the full picture. The scenario in the diagram above is a classic example: two requests just to render one screen.

This problem becomes dramatically worse with lists. If you need to display ten posts, each with its author's profile picture, and the posts endpoint doesn't include author details, you make one request to get the posts and then ten more requests to fetch each author's data.

This is the N+1 problem: one request to get N items, followed by N additional requests to enrich them. For a list of ten items, that is eleven network calls for a single screen.

Versioning: When APIs Can't Evolve Cleanly

As your app evolves, different screens need different shapes of the same data. You can't simply change an existing endpoint because other clients depend on its current response shape.

So you create /v2/users, then /v3/users, and soon you're maintaining multiple versions of the same endpoints, afraid to delete old ones because you cannot be certain which clients still use them.

Your API documentation becomes a graveyard of deprecated routes, and your backend team spends engineering time maintaining things that serve no active user need.

The Single Endpoint Approach

One Endpoint, Client-Defined Data

GraphQL replaces the many-endpoints model with a single endpoint, typically /graphql. Instead of the URL encoding what you want, the request body encodes it. Every operation (reading data, changing data, or listening to real-time events) is sent as a structured document to that same endpoint.

Here's the profile screen scenario from above, rewritten as a single GraphQL operation:

query GetUserProfile($userId: ID!) {
  user(id: $userId) {
    id
    name
    profilePic
    posts(last: 5) {
      id
      title
      likeCount
    }
  }
}

One request. One response. The data arrives in exactly the shape the query described:

{
  "data": {
    "user": {
      "id": "42",
      "name": "Atuoha Anthony",
      "profilePic": "https://cdn.example.com/atuoha.jpg",
      "posts": [
        { "id": "101", "title": "My First Post", "likeCount": 42 },
        { "id": "102", "title": "Flutter Tips", "likeCount": 118 }
      ]
    }
  }
}

Why GraphQL Doesn't Need Versioning

GraphQL's schema-first design eliminates the versioning problem almost entirely. When you add new fields or types to the schema, existing clients that don't request those new fields continue working without modification. When you want to deprecate a field, you mark it with the @deprecated directive in the schema.

Developer tooling surfaces that deprecation to client developers, giving them time to migrate away from it. Meanwhile, the field continues serving data until you are confident all clients have moved on. You never need to maintain parallel versions of the same endpoint.

Core GraphQL Concepts: A Deep Dive

The Schema: The Contract Between Client and Server

The schema is the foundation of every GraphQL API. Written in the Schema Definition Language (SDL), it's a formal declaration of every type of data your server can provide and every operation a client can perform. Both the server and the client read from it.

When you write a query in your Flutter app, your tooling validates it against the schema before a single network request is made. If you request a field that doesn't exist in the schema, the error is caught immediately at the query level, not at runtime in production.

Here is what a schema for a blog application looks like:

type User {
  id: ID!
  name: String!
  email: String!
  bio: String
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  likeCount: Int!
  comments: [Comment!]!
  publishedAt: String!
}

type Comment {
  id: ID!
  text: String!
  author: User!
}

type Query {
  user(id: ID!): User
  post(id: ID!): Post
  allPosts(page: Int, limit: Int): [Post!]!
}

type Mutation {
  createPost(title: String!, content: String!): Post!
  likePost(postId: ID!): Post!
  deletePost(postId: ID!): Boolean!
}

type Subscription {
  postAdded: Post!
  commentAdded(postId: ID!): Comment!
}

The ! after a type name means the field is non-nullable: it will never return null. [Post!]! means a non-null list of non-null Post objects. Query, Mutation, and Subscription are the root types: special types that define the entry points into the API.

As a Flutter developer you won't write the schema (that is the backend's job). But you must be able to read it fluently, because it tells you exactly what you can query and what shape the response will carry.

Types: The Building Blocks

GraphQL has two broad categories of types: scalar types and object types.

Scalar types are the leaf values in a query. They have no sub-fields and can't be broken down further.

The five built-in scalars are String, Int, Float, Boolean, and ID. ID is special in that it represents a unique identifier and is serialized as a string. Servers can also define custom scalars like DateTime, URL, or JSON to represent domain-specific value types.

Object types have named fields that resolve to either scalars or other object types. They form the graph in GraphQL, where you traverse relationships by nesting your field selections:

query {
  post(id: "17") {
    title       # scalar
    author {    # object type -- traversing a relationship
      name      # scalar nested inside the relationship
    }
  }
}

Enum types constrain a field to a defined set of values, preventing arbitrary strings from being used where only specific values are valid:

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

Input types are used specifically as complex arguments in mutations. Because regular object types can't be used as arguments, you define separate input types for structured mutation inputs:

input CreatePostInput {
  title: String!
  content: String!
  status: PostStatus!
}

type Mutation {
  createPost(input: CreatePostInput!): Post!
}

Queries: Reading Data

A query is the GraphQL operation for reading data. It's the GET of the GraphQL world. You declare the exact fields you want and the server returns exactly those.

query GetPostDetails($postId: ID!) {
  post(id: $postId) {
    id
    title
    content
    publishedAt
    author {
      id
      name
    }
    comments {
      id
      text
      author {
        name
      }
    }
    likeCount
  }
}

Let's break this down line by line so the structure is clear:

The word query declares the operation type, telling the server you're reading data, not writing it.

GetPostDetails is the operation name. It's optional but strongly recommended for debugging, logging, and code generation.

($postId: ID!) is the variable declaration: $postId is a placeholder of type ID! whose actual value will be supplied at runtime when the query is executed. post(id: $postId) calls the post field on the root Query type, passing the variable as the argument.

Everything inside curly braces is the selection set, the exact fields you want the server to return. Notice how author and comments are nested with their own selection sets. You're traversing the graph, following relationships declared in the schema, and the server resolves each relationship and includes it in the single response.

The response mirrors your query's shape exactly:

{
  "data": {
    "post": {
      "id": "17",
      "title": "Getting Started With GraphQL",
      "content": "GraphQL is a query language for APIs...",
      "publishedAt": "2024-01-15T10:30:00Z",
      "author": { "id": "42", "name": "Franklin Oladipo" },
      "comments": [
        {
          "id": "201",
          "text": "Great article!",
          "author": { "name": "Bede Hampo" }
        }
      ],
      "likeCount": 247
    }
  }
}

Mutations: Changing Data

A mutation is the GraphQL operation for modifying data: creating, updating, or deleting records. The syntax is identical to a query, with the single difference that you use the mutation keyword instead of query.

mutation CreateNewPost(\(title: String!, \)content: String!) {
  createPost(title: \(title, content: \)content) {
    id
    title
    publishedAt
    author {
      name
    }
  }
}

One of the most powerful aspects of mutations is that they return data. After creating a post, you can immediately ask for any fields from the newly created object within the same operation. Your UI can then update with the server's authoritative data without making a separate query afterward.

Unlike queries, mutations execute serially by default. If you send multiple mutations in a single request, they run one after another, not in parallel. This prevents race conditions when one mutation depends on the result of the previous one.

Subscriptions: Real-Time Data

A subscription is GraphQL's built-in mechanism for real-time updates. Instead of the client polling for new data, the server pushes data to the client whenever a relevant event occurs. Subscriptions are implemented over WebSockets and are a first-class part of the GraphQL specification.

subscription OnNewComment($postId: ID!) {
  commentAdded(postId: $postId) {
    id
    text
    author {
      name
      profilePic
    }
  }
}

When a client subscribes to commentAdded for a specific post, the server keeps the WebSocket connection open. Every time a new comment is added to that post, the server pushes the comment data to all connected subscribers instantly.

This is the right tool for chat applications, live notification feeds, real-time collaboration features, or any scenario where users expect the UI to react to server-side events without manually refreshing.

Variables: Making Queries Safe and Reusable

Variables are how you pass dynamic values into a GraphQL operation without embedding them directly in the query string. This separation is not just a convention but a strict requirement enforced by every GraphQL library for safety and efficiency reasons.

Without variables, dynamic values would have to be interpolated into the query string, which opens the door to injection attacks and prevents query-level caching. With variables, the query string is a fixed, immutable template. Only the variables change per request:

# The query is always this exact string. It never changes.
query GetUser($userId: ID!) {
  user(id: $userId) {
    name
  }
}

// The variables object changes per request.
{ "userId": "42" }

The server receives both and processes them separately. It never interpolates your variable values into the query string. This is the safe, correct pattern for dynamic data, and the graphql_flutter library enforces it throughout its API.

Fragments: Reusable Field Sets

As queries grow in complexity, you'll find yourself selecting the same set of fields from the same type across multiple queries. Fragments solve this with named, reusable chunks of a selection set:

# Define the fragment once on a specific type
fragment UserBasicInfo on User {
  id
  name
  profilePic
}

# Use it in as many queries as needed
query GetPost($postId: ID!) {
  post(id: $postId) {
    title
    author {
      ...UserBasicInfo   # spread the fragment here
    }
    comments {
      text
      author {
        ...UserBasicInfo  # and here
      }
    }
  }
}

The ...UserBasicInfo spread tells the server to replace that spread with the full set of fields defined in the fragment. Fragments are especially valuable in component-driven UIs like Flutter, where each widget can define a fragment for the exact data it needs, and screen-level queries can be assembled by composing fragments from their child widgets.

Resolvers: How the Server Fulfills Queries

You won't write resolvers as a Flutter developer, but understanding them conceptually makes you a more effective consumer of GraphQL APIs and helps you reason about performance implications.

A resolver is a function on the server that knows how to fetch the data for one specific field. Every field in the schema has a resolver. When a query arrives, the GraphQL runtime walks through the selection set and calls the appropriate resolver for each requested field, assembling the results into the shape the client declared.

Query: { user(id: "42") { name posts { title } } }

Server execution:
  1. Call resolver for Query.user("42")  -> { id: "42", name: "Tony" }
  2. Call resolver for User.posts("42") -> [{ title: "Post 1" }]
  3. Assemble result                    -> { user: { name: "Tony", posts: [...] } }

Each resolver independently fetches its piece of data, which might come from a relational database, a microservice, a third-party API, or an in-memory cache. The GraphQL runtime stitches all the pieces together. The client never knows or cares about the implementation details. It declares what it wants and receives the assembled result.

GraphQL Architecture in Flutter

How the Pieces Connect

When you use GraphQL in a Flutter app, four distinct layers work together. Understanding their roles and the boundaries between them is essential before writing a single line of application code.

The Flutter UI layer contains your widgets. They declare what data they need using Query, Mutation, and Subscription widgets (or hooks). They know nothing about HTTP, WebSockets, or caching. They describe their data requirements and react to results.
The GraphQL Client is the engine at the center of everything. The graphql_flutter package manages the connection to your server, the normalized cache, request queuing, deduplication, and reactive result broadcasting to widgets.
The Link Chain is a composable middleware pipeline that every request passes through before reaching the server. Links can add authentication headers, log requests, handle errors, retry failed requests, and route traffic between HTTP and WebSocket connections based on operation type.
The GraphQL Server receives the operation, validates it against the schema, executes the resolvers, and returns the JSON response.

The Normalized Cache: GraphQL's Secret Weapon

The GraphQL client's cache is one of its most powerful features and one of the most commonly misunderstood.

Unlike a simple HTTP cache that stores raw response blobs, the GraphQL cache is a normalized object store. Every object is stored once, identified by its type and ID. The cache key for a post with id "17" of type Post is Post:17. If that same post appears in ten different query results across ten different screens, it's stored only once.

The consequence of this is significant. When a mutation updates that post, the cache updates its single stored copy. Every widget in your app that previously fetched that post immediately receives the updated data and rebuilds. A like count updated on a post detail screen is reflected on the feed screen, the user profile screen, and anywhere else that post was displayed, all without re-fetching, all automatically, triggered by a single cache write.

This shared, reactive normalized store is what makes well-built GraphQL apps feel so fluid. It's also what enables optimistic UI updates to work across the entire widget tree simultaneously.

Setting Up GraphQL in Flutter

Adding the Dependency

Open your pubspec.yaml and add the package:

dependencies:
  flutter:
    sdk: flutter
  graphql_flutter: ^5.3.0

Then run:

flutter pub get

Android Build Configuration

This step is non-negotiable for Android targets and is easy to miss. Open android/app/build.gradle and ensure the Java compatibility settings are present:

android {
    compileSdkVersion 34

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

Also update android/gradle/wrapper/gradle-wrapper.properties to use Gradle 8.4:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip

Skipping this step results in cryptic Java compatibility errors at build time that are difficult to diagnose if you don't know to look here.

Initializing Hive for Persistent Caching

graphql_flutter uses Hive (via hive_ce) for on-disk persistent caching. This means the cache survives app restarts: a user who opens your app without an internet connection will still see previously loaded data rather than an empty screen.

To enable this, you must call initHiveForFlutter() before runApp(), and it must be awaited:

import 'package:flutter/material.dart';
import 'package:graphql_flutter/graphql_flutter.dart';

void main() async {
  // Required before calling any Flutter plugin code before runApp().
  // initHiveForFlutter() uses platform channels internally to locate
  // the correct storage directory on each platform.
  WidgetsFlutterBinding.ensureInitialized();

  // Sets up the Hive storage directory and registers necessary adapters.
  // After this call, HiveStore is ready to be used inside GraphQLCache.
  await initHiveForFlutter();

  runApp(const MyApp());
}

If you prefer not to persist the cache across sessions, you can skip this initialization and use InMemoryStore instead of HiveStore when creating the cache. For production apps, HiveStore is almost always the right choice.

Creating the GraphQL Client

The GraphQLClient is the central object in the entire system. It's created once and provided to the widget tree through GraphQLProvider.

Here is a full setup with a line-by-line explanation of every decision:

import 'package:flutter/material.dart';
import 'package:graphql_flutter/graphql_flutter.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    // HttpLink is the terminating link: the final link in the chain
    // that actually sends the HTTP POST request to your server.
    // It takes your GraphQL endpoint URL as its only required argument.
    final HttpLink httpLink = HttpLink(
      'https://api.yourapp.com/graphql',
    );

    // AuthLink is a non-terminating link that runs before HttpLink.
    // Its sole job is to attach an Authorization header to every request.
    // getToken is async, so you can read from secure storage, a token
    // refresh service, or any other async source.
    final AuthLink authLink = AuthLink(
      getToken: () async {
        // In production, read this from FlutterSecureStorage or
        // your auth state management layer, never from plain storage.
        final token = await _getTokenFromStorage();
        return 'Bearer $token';
      },
    );

    // concat() assembles the link chain. Requests flow left to right:
    // AuthLink runs first (attaching the header), then HttpLink runs
    // (sending the actual HTTP request). You can insert as many
    // non-terminating links as needed between them.
    final Link link = authLink.concat(httpLink);

    // ValueNotifier is required by GraphQLProvider.
    // Wrapping the client in a ValueNotifier allows you to replace
    // the entire client at runtime (for example, on user logout to
    // clear the cache) and GraphQLProvider will rebuild all its
    // descendants automatically with the new client.
    final ValueNotifier client = ValueNotifier(
      GraphQLClient(
        link: link,
        // HiveStore provides persistent on-disk caching.
        // Swap HiveStore() for InMemoryStore() if you want the
        // cache to be cleared on every app restart.
        cache: GraphQLCache(store: HiveStore()),
      ),
    );

    // GraphQLProvider injects the client into the widget tree via
    // InheritedWidget. Any descendant can access the client through
    // GraphQLProvider.of(context). Wrapping MaterialApp means the
    // client is available on every screen in your app.
    return GraphQLProvider(
      client: client,
      child: MaterialApp(
        title: 'My GraphQL App',
        theme: ThemeData(
          colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
          useMaterial3: true,
        ),
        home: const HomePage(),
      ),
    );
  }

  Future _getTokenFromStorage() async {
    // Replace with your actual secure storage implementation.
    return 'your-auth-token';
  }
}

Adding WebSocket Support for Subscriptions

If your app uses real-time subscriptions, you need a WebSocketLink alongside the HttpLink. The two are joined using Link.split, which routes each request to the correct transport based on its operation type:

final HttpLink httpLink = HttpLink('https://api.yourapp.com/graphql');

final WebSocketLink webSocketLink = WebSocketLink(
  // Use wss:// for secure WebSockets in production.
  // Use ws:// only for local development.
  'wss://api.yourapp.com/graphql',
  config: const SocketClientConfig(
    autoReconnect: true,
    delayBetweenConnectAttempts: Duration(seconds: 5),
  ),
);

// Link.split evaluates its predicate for each incoming request.
// If the predicate returns true, the first (left) link handles it.
// If false, the second (right) link handles it.
// request.isSubscription is true for subscription operations.
final Link link = authLink.concat(
  Link.split(
    (request) => request.isSubscription,
    webSocketLink,  // subscriptions go here
    httpLink,       // queries and mutations go here
  ),
);

The authLink sits before the split so it runs for all operation types. Both HTTP and WebSocket transports typically require authentication.

Using GraphQL in Flutter: Queries, Mutations, and Subscriptions

Queries: Fetching and Displaying Data

The Query widget executes a GraphQL query and rebuilds whenever the result state changes. It's the primary mechanism for loading data on a screen.

import 'package:flutter/material.dart';
import 'package:graphql_flutter/graphql_flutter.dart';

// Always define query strings as top-level constants, never inside build().
// The `r` prefix creates a raw string so dollar signs and backslashes
// are not treated as Dart escape sequences or string interpolations.
// gql() parses this string into a DocumentNode AST that the client executes.
const String fetchPostsQuery = r'''
  query FetchPosts(\(limit: Int!, \)page: Int!) {
    allPosts(limit: \(limit, page: \)page) {
      id
      title
      publishedAt
      likeCount
      author {
        name
        profilePic
      }
    }
  }
''';

class PostListScreen extends StatelessWidget {
  const PostListScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Posts')),
      body: Query(
        options: QueryOptions(
          document: gql(fetchPostsQuery),

          // Variables are passed as a plain Dart Map.
          // The library serializes them to JSON and sends them alongside
          // the query string as a separate field in the request body.
          variables: const {'limit': 10, 'page': 1},

          // cacheAndNetwork: return cached data immediately if available,
          // then fire a background network request and rebuild with fresh
          // data when it arrives. Users get instant perceived load time
          // from the cache while staying current with the server.
          fetchPolicy: FetchPolicy.cacheAndNetwork,
        ),

        // The builder function is called on every state change:
        // when loading begins, when data arrives, when an error occurs,
        // and when cached data is updated by another operation.
        //
        // result  -- current state: loading status, data, exceptions
        // refetch -- callback to manually re-execute the query
        // fetchMore -- callback for pagination (covered later)
        builder: (QueryResult result, {VoidCallback? refetch, FetchMore? fetchMore}) {

          // Always check for exceptions first.
          // OperationException wraps both network-level and GraphQL-level errors.
          if (result.hasException) {
            return Center(
              child: Column(
                mainAxisSize: MainAxisSize.min,
                children: [
                  const Icon(Icons.error_outline, size: 48, color: Colors.red),
                  const SizedBox(height: 12),
                  Text(
                    result.exception?.graphqlErrors.firstOrNull?.message
                        ?? result.exception?.linkException.toString()
                        ?? 'An error occurred',
                    textAlign: TextAlign.center,
                  ),
                  const SizedBox(height: 16),
                  ElevatedButton(
                    onPressed: refetch,
                    child: const Text('Try Again'),
                  ),
                ],
              ),
            );
          }

          // isLoading is true only on the initial load when no cached data
          // exists. With cacheAndNetwork, if cache data is available,
          // isLoading is false even while a background request is running.
          if (result.isLoading && result.data == null) {
            return const Center(child: CircularProgressIndicator());
          }

          // result.data is a Map that mirrors
          // the shape you declared in your query's selection set.
          final List? posts =
              result.data?['allPosts'] as List?;

          if (posts == null || posts.isEmpty) {
            return const Center(child: Text('No posts found.'));
          }

          return RefreshIndicator(
            onRefresh: () async => refetch?.call(),
            child: ListView.builder(
              itemCount: posts.length,
              itemBuilder: (context, index) {
                final post = posts[index] as Map;
                return PostCard(post: post);
              },
            ),
          );
        },
      ),
    );
  }
}

class PostCard extends StatelessWidget {
  final Map post;

  const PostCard({super.key, required this.post});

  @override
  Widget build(BuildContext context) {
    final author = post['author'] as Map?;

    return Card(
      margin: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
      child: ListTile(
        leading: author?['profilePic'] != null
            ? CircleAvatar(
                backgroundImage:
                    NetworkImage(author!['profilePic'] as String),
              )
            : const CircleAvatar(child: Icon(Icons.person)),
        title: Text(post['title'] as String? ?? ''),
        subtitle: Text('By ${author?['name'] ?? 'Unknown'}'),
        trailing: Row(
          mainAxisSize: MainAxisSize.min,
          children: [
            const Icon(Icons.favorite, color: Colors.red, size: 16),
            const SizedBox(width: 4),
            Text('${post['likeCount'] ?? 0}'),
          ],
        ),
      ),
    );
  }
}

The cacheAndNetwork fetch policy is worth emphasizing. When a user navigates to this screen for the second time, the cached data renders with zero network wait. Simultaneously, a network request runs in the background. When it completes, the widget rebuilds with the fresh data.

The builder is called twice: once with the cached data and once with the updated network data. For most feed-style screens, this produces the best user experience: instant perceived performance combined with freshness.

Using Hooks for Queries

If your team prefers a more functional style, graphql_flutter provides the useQuery hook that works with flutter_hooks. The behavior is identical to the Query widget, but the API avoids deeply nested builder functions:

import 'package:flutter/material.dart';
import 'package:flutter_hooks/flutter_hooks.dart';
import 'package:graphql_flutter/graphql_flutter.dart';

// HookWidget replaces StatelessWidget when using hooks.
class PostListScreen extends HookWidget {
  const PostListScreen({super.key});

  @override
  Widget build(BuildContext context) {
    // useQuery returns a QueryHookResult containing the result and helpers.
    final queryResult = useQuery(
      QueryOptions(
        document: gql(fetchPostsQuery),
        variables: const {'limit': 10, 'page': 1},
        fetchPolicy: FetchPolicy.cacheAndNetwork,
      ),
    );

    final result = queryResult.result;
    final refetch = queryResult.refetch;

    if (result.hasException) {
      return Scaffold(
        body: Center(child: Text(result.exception.toString())),
      );
    }

    if (result.isLoading && result.data == null) {
      return const Scaffold(
        body: Center(child: CircularProgressIndicator()),
      );
    }

    final posts = result.data?['allPosts'] as List? ?? [];

    return Scaffold(
      appBar: AppBar(title: const Text('Posts')),
      body: RefreshIndicator(
        onRefresh: () async => refetch(),
        child: ListView.builder(
          itemCount: posts.length,
          itemBuilder: (context, index) {
            final post = posts[index] as Map;
            return PostCard(post: post);
          },
        ),
      ),
    );
  }
}

Both styles are fully supported and functionally equivalent. The widget-based API is more approachable for developers coming from non-React backgrounds. The hooks API produces cleaner code when a widget composes multiple operations, because it avoids the callback nesting that builders introduce.

Mutations: Triggering Data Changes

The Mutation widget gives you a RunMutation function in its builder. Unlike Query, which executes automatically on render, Mutation waits for you to call runMutation. Mutations are triggered by user actions, not automatically on widget construction.

const String likePostMutation = r'''
  mutation LikePost($postId: ID!) {
    likePost(postId: $postId) {
      id
      likeCount
      viewerHasLiked
    }
  }
''';

class LikeButton extends StatelessWidget {
  final String postId;
  final bool initiallyLiked;
  final int likeCount;

  const LikeButton({
    super.key,
    required this.postId,
    required this.initiallyLiked,
    required this.likeCount,
  });

  @override
  Widget build(BuildContext context) {
    return Mutation(
      options: MutationOptions(
        document: gql(likePostMutation),

        // update runs after the mutation completes.
        // Because our mutation returns the updated post with its id,
        // likeCount, and viewerHasLiked, the cache can normalize the result.
        // It updates the cached Post:postId object automatically, and any
        // Query widget that previously fetched this post rebuilds with the
        // new like count. Manual cache writes are only needed when you are
        // adding or removing items from cached lists.
        update: (GraphQLDataProxy cache, QueryResult? result) {
          // Automatic normalization handles this case cleanly.
        },

        // onCompleted runs after a successful mutation.
        // Use it for side effects: snackbars, navigation, analytics events.
        onCompleted: (dynamic resultData) {
          if (resultData != null) {
            ScaffoldMessenger.of(context).showSnackBar(
              const SnackBar(content: Text('Post liked!')),
            );
          }
        },

        // onError handles mutation failures.
        onError: (OperationException? error) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
              content: Text(
                error?.graphqlErrors.firstOrNull?.message
                    ?? 'Failed to like post',
              ),
            ),
          );
        },
      ),

      // runMutation: call this to fire the mutation.
      // result: the state of the last mutation run, null before the first call.
      builder: (RunMutation runMutation, QueryResult? result) {
        final isLoading = result?.isLoading ?? false;
        final hasLiked = result?.data?['likePost']?['viewerHasLiked'] as bool?
            ?? initiallyLiked;
        final currentCount =
            result?.data?['likePost']?['likeCount'] as int? ?? likeCount;

        return GestureDetector(
          onTap: isLoading
              ? null
              : () => runMutation({'postId': postId}),
          child: Row(
            mainAxisSize: MainAxisSize.min,
            children: [
              isLoading
                  ? const SizedBox(
                      width: 20,
                      height: 20,
                      child: CircularProgressIndicator(strokeWidth: 2),
                    )
                  : Icon(
                      hasLiked ? Icons.favorite : Icons.favorite_border,
                      color: hasLiked ? Colors.red : Colors.grey,
                    ),
              const SizedBox(width: 4),
              Text('$currentCount'),
            ],
          ),
        );
      },
    );
  }
}

The relationship between update, onCompleted, and onError is a frequent source of confusion. Think of them this way: update is for cache operations and runs even for optimistic results, onCompleted is for side effects after success, and onError is for side effects after failure.

Never put navigation logic inside update because it runs before the widget rebuild cycle is complete, which leads to navigation errors.

Subscriptions: Receiving Real-Time Events

The Subscription widget opens a WebSocket connection and calls its builder function every time the server pushes a new event. Each call to the builder receives the latest single event, not an accumulated history of all past events. Accumulating and managing state over time is your responsibility as the developer.

const String commentAddedSubscription = r'''
  subscription CommentAdded($postId: ID!) {
    commentAdded(postId: $postId) {
      id
      text
      author {
        id
        name
        profilePic
      }
    }
  }
''';

class CommentsSection extends StatefulWidget {
  final String postId;
  const CommentsSection({super.key, required this.postId});

  @override
  State createState() => _CommentsSectionState();
}

class _CommentsSectionState extends State {
  final List> _comments = [];

  @override
  Widget build(BuildContext context) {
    return Subscription(
      options: SubscriptionOptions(
        document: gql(commentAddedSubscription),
        variables: {'postId': widget.postId},
      ),
      builder: (QueryResult result) {
        if (result.isLoading) {
          // For subscriptions, isLoading means the WebSocket connection
          // is being established, not that server data is loading.
          return const Center(child: CircularProgressIndicator());
        }

        if (result.hasException) {
          return Text('Subscription error: ${result.exception}');
        }

        if (result.data != null) {
          final newComment =
              result.data!['commentAdded'] as Map?;
          if (newComment != null) {
            // addPostFrameCallback prevents calling setState during
            // the current build phase, which would throw a Flutter error.
            WidgetsBinding.instance.addPostFrameCallback((_) {
              if (mounted) {
                setState(() {
                  final exists =
                      _comments.any((c) => c['id'] == newComment['id']);
                  if (!exists) _comments.insert(0, newComment);
                });
              }
            });
          }
        }

        if (_comments.isEmpty) {
          return const Center(child: Text('No comments yet. Be the first!'));
        }

        return ListView.builder(
          itemCount: _comments.length,
          itemBuilder: (context, index) {
            final comment = _comments[index];
            final author = comment['author'] as Map?;
            return ListTile(
              leading: CircleAvatar(
                backgroundImage: author?['profilePic'] != null
                    ? NetworkImage(author!['profilePic'] as String)
                    : null,
                child: author?['profilePic'] == null
                    ? const Icon(Icons.person)
                    : null,
              ),
              title: Text(author?['name'] as String? ?? 'Anonymous'),
              subtitle: Text(comment['text'] as String? ?? ''),
            );
          },
        );
      },
    );
  }
}

In production code, you wouldn't manage subscription state in a StatefulWidget. Instead, you would stream subscription events into a Bloc or provider that accumulates them, and the widget would simply render the state emitted by that Bloc.

Advanced Concepts

Caching Strategies: Choosing the Right Policy

Picking the correct fetch policy for each query is one of the most impactful decisions you make in a GraphQL Flutter app. The wrong policy makes your app feel slow or shows stale data at the wrong moment. The right policy makes it feel native.

FetchPolicy.cacheFirst checks the cache before touching the network. If the data is already cached, it returns immediately without making a network request. A network call only happens if the cache has nothing.

Use this for data that almost never changes during a session, like a list of countries, a user's account settings, or configuration values loaded at startup.

FetchPolicy.cacheAndNetwork returns cached data immediately while firing a background network request simultaneously. When the network response arrives, the cache updates and the widget rebuilds with fresh data.

This is the right default for most content screens: fast perceived load from the cache, with freshness guaranteed by the background fetch.

FetchPolicy.networkOnly always goes to the network and ignores the cache completely for reading. The response is still written to the cache for future use.

Use this when data freshness is non-negotiable, such as a bank balance, live inventory count, or the result of a payment operation.

FetchPolicy.cacheOnly reads exclusively from the cache and never makes a network request. If the data isn't cached, it returns null.

This is primarily useful in offline-first apps where you have pre-populated the cache and want to guarantee no network calls.

FetchPolicy.noCache always goes to the network and does not read from or write to the cache. Use this for one-time operations where caching would be actively harmful.

// Account settings -- loaded once, changes rarely during a session
QueryOptions(
  document: gql(getUserSettingsQuery),
  fetchPolicy: FetchPolicy.cacheFirst,
)

// News feed -- instant load from cache, background refresh for freshness
QueryOptions(
  document: gql(getNewsFeedQuery),
  fetchPolicy: FetchPolicy.cacheAndNetwork,
)

// Payment history -- must always reflect the server's current state
QueryOptions(
  document: gql(getPaymentHistoryQuery),
  fetchPolicy: FetchPolicy.networkOnly,
)

Pagination with fetchMore

Most real apps deal with lists too large to load at once. The fetchMore function exposed in the Query builder handles pagination by executing a new query and merging its results with the existing ones.

const String fetchPostsWithPaginationQuery = r'''
  query FetchPosts(\(cursor: String, \)limit: Int!) {
    postsConnection(after: \(cursor, first: \)limit) {
      edges {
        node {
          id
          title
          likeCount
        }
        cursor
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
''';

class PaginatedPostList extends StatelessWidget {
  const PaginatedPostList({super.key});

  @override
  Widget build(BuildContext context) {
    return Query(
      options: QueryOptions(
        document: gql(fetchPostsWithPaginationQuery),
        variables: const {'limit': 10, 'cursor': null},
        fetchPolicy: FetchPolicy.cacheAndNetwork,
      ),
      builder: (QueryResult result, {VoidCallback? refetch, FetchMore? fetchMore}) {
        if (result.isLoading && result.data == null) {
          return const Center(child: CircularProgressIndicator());
        }

        final connection =
            result.data?['postsConnection'] as Map?;
        final edges = connection?['edges'] as List? ?? [];
        final pageInfo =
            connection?['pageInfo'] as Map?;
        final hasNextPage = pageInfo?['hasNextPage'] as bool? ?? false;
        final endCursor = pageInfo?['endCursor'] as String?;

        return ListView.builder(
          itemCount: edges.length + (hasNextPage ? 1 : 0),
          itemBuilder: (context, index) {
            if (index == edges.length) {
              return Padding(
                padding: const EdgeInsets.all(16),
                child: ElevatedButton(
                  onPressed: () {
                    final FetchMoreOptions opts = FetchMoreOptions(
                      variables: {'cursor': endCursor, 'limit': 10},

                      // updateQuery merges the new page with all previous data.
                      // You must return the merged dataset from this function.
                      // previousResultData: everything fetched so far.
                      // fetchMoreResultData: the data from this new page only.
                      updateQuery: (previousResultData, fetchMoreResultData) {
                        final List allEdges = [
                          ...previousResultData['postsConnection']['edges']
                              as List,
                          ...fetchMoreResultData['postsConnection']['edges']
                              as List,
                        ];
                        // Assign the merged list into fetchMoreResultData
                        // and return it. The library uses the returned
                        // value as the new authoritative result for the query.
                        fetchMoreResultData['postsConnection']['edges'] = allEdges;
                        return fetchMoreResultData;
                      },
                    );

                    fetchMore!(opts);
                  },
                  child: const Text('Load More'),
                ),
              );
            }

            final node = edges[index]['node'] as Map;
            return PostCard(post: node);
          },
        );
      },
    );
  }
}

The most common mistake with fetchMore is mutating previousResultData directly instead of building a new list. Always treat both arguments as read-only, construct the merged list as a new object, assign it into fetchMoreResultData, and return fetchMoreResultData.

Optimistic UI Updates

Optimistic UI is a pattern where the interface updates immediately after a user action, before the server has confirmed the change. If the server confirms, the optimistic data is silently replaced with the authoritative server data. If the server rejects the change, the cache rolls back to its pre-mutation state automatically.

The result is an app that feels dramatically faster. The user taps a like button, the heart turns red, and the count increments instantly. No spinner, no wait. If the network request fails, the UI reverts cleanly without any manual rollback code.

Mutation(
  options: MutationOptions(
    document: gql(likePostMutation),
    update: (GraphQLDataProxy cache, QueryResult? result) {
      // When the real server response arrives, the cache normalizes
      // it automatically, replacing the optimistic values with the
      // server's authoritative data.
    },
  ),
  builder: (RunMutation runMutation, QueryResult? result) {
    return IconButton(
      onPressed: () {
        runMutation(
          {'postId': postId},
          // optimisticResult must exactly match the shape of your
          // mutation's return type, including __typename.
          // The cache uses __typename + id as the normalization key.
          optimisticResult: {
            'likePost': {
              '__typename': 'Post',
              'id': postId,
              'likeCount': currentLikeCount + 1,
              'viewerHasLiked': true,
            }
          },
        );
      },
      icon: const Icon(Icons.favorite_border),
    );
  },
);

When runMutation is called with an optimisticResult, the cache immediately applies those values and broadcasts updates to every widget that holds data for that cached object. When the real network response arrives moments later, the cache updates once more with the server's values, triggering a final rebuild.

Error Handling: A Production-Grade Approach

GraphQL errors come in two distinct categories, and handling both correctly is essential for a reliable production app.

Network errors occur at the transport layer: no internet connection, DNS failure, server unreachable, or connection timeout. These surface as a LinkException inside result.exception.

GraphQL errors occur inside the GraphQL execution layer: authentication failures, authorization violations, schema validation errors, or custom business logic errors defined by your server team. These surface as a list of GraphQLError objects.

Importantly, GraphQL allows partial results where a response contains both data and errors simultaneously, if some fields resolved successfully and some failed.

Widget _buildFromResult(
    BuildContext context, QueryResult result, VoidCallback? refetch) {
  if (result.hasException) {
    final exception = result.exception!;

    // Check for network-level errors first
    if (exception.linkException != null) {
      if (exception.linkException is NetworkException) {
        return _NoInternetWidget(onRetry: refetch);
      }
      return _ServerErrorWidget(onRetry: refetch);
    }

    // Check for GraphQL-level errors
    if (exception.graphqlErrors.isNotEmpty) {
      final firstError = exception.graphqlErrors.first;
      // Many servers include a machine-readable code in the extensions map
      final errorCode = firstError.extensions?['code'] as String?;

      switch (errorCode) {
        case 'UNAUTHENTICATED':
          WidgetsBinding.instance.addPostFrameCallback((_) {
            Navigator.of(context).pushReplacementNamed('/login');
          });
          return const SizedBox.shrink();

        case 'FORBIDDEN':
          return const _AccessDeniedWidget();

        case 'NOT_FOUND':
          return const _NotFoundWidget();

        default:
          return _GenericErrorWidget(
            message: firstError.message,
            onRetry: refetch,
          );
      }
    }
  }

  // success state handled here...
  return const SizedBox.shrink();
}

Authentication: Transparent Token Refresh

In production apps, access tokens expire. Rather than letting expired tokens cause request failures that users must recover from manually, you can build a custom link that intercepts authentication errors and refreshes the token transparently before retrying the original request.

class AuthRefreshLink extends Link {
  final Future Function() refreshToken;
  final Future Function() onAuthFailure;

  AuthRefreshLink({required this.refreshToken, required this.onAuthFailure});

  @override
  Stream request(Request request, [NextLink? forward]) async* {
    await for (final result in forward!(request)) {
      final isAuthError = (result.errors ?? [])
          .any((e) => e.extensions?['code'] == 'UNAUTHENTICATED');

      if (isAuthError) {
        final newToken = await refreshToken();

        if (newToken == null) {
          await onAuthFailure(); // Trigger logout
          return;
        }

        // Retry the original request with the new token
        final retryRequest = request.updateContextEntry(
          (headers) => HttpLinkHeaders(
            headers: {
              ...headers?.headers ?? {},
              'Authorization': 'Bearer $newToken',
            },
          ),
        );

        yield* forward(retryRequest);
      } else {
        yield result;
      }
    }
  }
}

This link sits in the chain before HttpLink. When an UNAUTHENTICATED error arrives, it refreshes the token, replays the original request, and the widget receives the successful data as if nothing unusual occurred. If the token refresh itself fails, onAuthFailure is called, which triggers a logout flow.

Best Practices in Real Apps

Project Structure That Scales

Scattering query strings across widget files is one of the fastest ways to create an unmaintainable codebase. Here's a folder structure that keeps GraphQL operations organized and consistently discoverable:

lib/
  graphql/
    client.dart              -- GraphQLClient setup, exported globally
    queries/
      post_queries.dart      -- All post-related queries
      user_queries.dart      -- All user-related queries
    mutations/
      post_mutations.dart
      auth_mutations.dart
    subscriptions/
      comment_subs.dart
    fragments/
      post_fragments.dart    -- Reusable post field sets
      user_fragments.dart    -- Reusable user field sets

  models/
    post.dart                -- Typed Dart models parsed from GraphQL data
    user.dart

  repositories/
    post_repository.dart     -- Data access abstraction layer

  blocs/
    post_bloc.dart           -- Business logic and state

  screens/
    post_list/
      post_list_screen.dart
      widgets/
        post_card.dart
        like_button.dart

Composing Queries from Fragments

Define fragments in dedicated files and compose queries by string interpolation. This ensures that field sets stay consistent across queries and schema changes propagate from a single definition:

// lib/graphql/fragments/post_fragments.dart

const String postBasicFieldsFragment = r'''
  fragment PostBasicFields on Post {
    id
    title
    publishedAt
    likeCount
  }
''';

const String postAuthorFragment = r'''
  fragment PostAuthorFields on Post {
    author {
      id
      name
      profilePic
    }
  }
''';

// lib/graphql/queries/post_queries.dart

import 'package:your_app/graphql/fragments/post_fragments.dart';

const String fetchPostsQuery = '''
  $postBasicFieldsFragment
  $postAuthorFragment

  query FetchPosts(\\(limit: Int!, \\)page: Int!) {
    allPosts(limit: \\(limit, page: \\)page) {
      ...PostBasicFields
      ...PostAuthorFields
    }
  }
''';

Parsing GraphQL Data into Typed Models

Working directly with Map throughout your business logic is fragile and error-prone. A typo in a string key causes a silent null at runtime, not a compile-time error. Define typed model classes and parse the GraphQL response at the data layer boundary:

// lib/models/post.dart

class Post {
  final String id;
  final String title;
  final String content;
  final int likeCount;
  final DateTime publishedAt;
  final User author;

  const Post({
    required this.id,
    required this.title,
    required this.content,
    required this.likeCount,
    required this.publishedAt,
    required this.author,
  });

  factory Post.fromMap(Map map) {
    return Post(
      id: map['id'] as String,
      title: map['title'] as String,
      content: map['content'] as String,
      likeCount: map['likeCount'] as int? ?? 0,
      publishedAt: DateTime.parse(map['publishedAt'] as String),
      author: User.fromMap(map['author'] as Map),
    );
  }
}

Integrating with Bloc and a Repository Layer

For production apps, placing Query and Mutation widgets directly in your screens couples your UI tightly to GraphQL. Introducing a repository layer that wraps GraphQL operations, with Bloc mediating between the repository and the UI, gives you proper separation of concerns:

// lib/repositories/post_repository.dart

class PostRepository {
  final GraphQLClient _client;

  PostRepository(this._client);

  Future> fetchPosts({int page = 1, int limit = 10}) async {
    final result = await _client.query(
      QueryOptions(
        document: gql(fetchPostsQuery),
        variables: {'page': page, 'limit': limit},
        fetchPolicy: FetchPolicy.cacheAndNetwork,
      ),
    );

    if (result.hasException) throw _mapException(result.exception!);

    return (result.data!['allPosts'] as List)
        .cast>()
        .map(Post.fromMap)
        .toList();
  }

  Future likePost(String postId) async {
    final result = await _client.mutate(
      MutationOptions(
        document: gql(likePostMutation),
        variables: {'postId': postId},
      ),
    );

    if (result.hasException) throw _mapException(result.exception!);

    return Post.fromMap(
      result.data!['likePost'] as Map,
    );
  }

  Stream watchNewPosts() {
    return _client
        .subscribe(
            SubscriptionOptions(document: gql(postAddedSubscription)))
        .where((result) => !result.hasException && result.data != null)
        .map((result) => Post.fromMap(
              result.data!['postAdded'] as Map,
            ));
  }

  Exception _mapException(OperationException e) {
    if (e.linkException != null) {
      return NetworkException('No internet connection');
    }
    return ApiException(
      e.graphqlErrors.firstOrNull?.message ?? 'Unknown error',
    );
  }
}

With this architecture, your Bloc knows nothing about GraphQL. Your screens know nothing about GraphQL. GraphQL is an implementation detail of the repository. Your UI and business logic can be unit tested without mocking GraphQL at all, which is the mark of a well-structured data layer.

When to Use GraphQL and When Not To

Where GraphQL Excels

GraphQL is the right choice when your application is genuinely complex and data-intensive. If your screens need data from multiple related entities simultaneously, and different screens need different subsets of the same underlying data, client-driven fetching pays for itself almost immediately.

Mobile apps are a particularly strong fit because bandwidth and battery are constrained resources, and the precision of GraphQL queries has a direct, measurable impact on both.

It also makes excellent sense when you serve multiple client types: a web app, a mobile app, a tablet layout, and perhaps a smartwatch companion, all consuming the same API. With REST, you either build bespoke endpoints for each client or force every client to over-fetch from a generic endpoint. With GraphQL, each client queries precisely what it needs from a single unified schema.

Real-time features are a natural fit as well. Subscriptions are a first-class part of the GraphQL protocol, not an afterthought. Combined with the normalized cache, new data arriving over a subscription can update cached objects that multiple screens share simultaneously.

And if your team values strong typing and self-documenting APIs, GraphQL delivers in a way that REST can't match without substantial additional tooling. The schema is a living, explorable contract. Combined with code generation tools like graphql_codegen, you can achieve end-to-end type safety from the schema definition all the way to your Dart widgets.

Where GraphQL is the Wrong Choice

GraphQL adds genuine complexity: a schema to maintain, resolvers to write, a link chain to configure, and a normalized cache whose behavior you must understand deeply to use correctly.

For simple CRUD applications like a settings screen, a contact form, or a basic registration flow, that complexity rarely pays off. REST is simpler to set up, simpler to debug, and more familiar to a wider range of developers.

If your team has no prior GraphQL experience and you're under a tight delivery deadline, the learning curve is real and legitimate. GraphQL can slow a team down before it speeds them up. That tradeoff deserves honest consideration before committing to the technology.

File uploads, while technically possible in GraphQL via the multipart request spec, are more complex to implement than a straightforward multipart POST to a REST endpoint. If uploading files is a core part of your app's functionality, REST handles it more naturally.

GraphQL is also harder to explore for third-party developers who want to test your API with simple curl commands. For public-facing developer APIs intended to be accessible to a broad audience with diverse tooling, REST is the more approachable and conventional choice.

Common Mistakes

Ignoring How the Normalized Cache Works

The most widespread mistake among developers new to GraphQL is not understanding normalization and then fighting the cache. You run a mutation, the server updates the data, but the UI doesn't refresh.

This typically happens for one of three reasons:

The mutation doesn't return the updated fields, so the cache receives no new data to normalize. Always return the full set of fields your UI needs from every mutation response.
The returned object doesn't include an id field, and often __typename as well, so the cache can't identify which stored object to update. The cache uses __typename concatenated with id as the cache key. If either is missing, normalization fails silently and the update has no visible effect.
The mutation adds or removes an item from a list, and the cache doesn't update the list automatically. The cache only updates objects it can identify by their key. It has no mechanism for knowing that a new comment should be appended to a post's comment list. You must handle list mutations manually in the update callback using cache.writeQuery or cache.writeFragment.

Defining Query Strings Inside the Build Method

When a query string is defined as a local variable inside build(), Dart recreates it on every rebuild, and gql() re-parses the string into an AST document object on every call. For simple widgets this is inconsequential in isolation, but it's unnecessary work that compounds across a complex widget tree. Always define query strings as top-level const values:

// Wrong -- recreated and re-parsed on every build() call
Widget build(BuildContext context) {
  final query = '''
    query { ... }
  ''';
  return Query(options: QueryOptions(document: gql(query)), ...);
}

// Right -- parsed once at startup, reused across every rebuild
const String myQuery = r'''
  query { ... }
''';

Widget build(BuildContext context) {
  return Query(options: QueryOptions(document: gql(myQuery)), ...);
}

Using `networkOnly` for Everything

Some developers, burned by stale cache bugs, set every single query to networkOnly. This solves the staleness problem by creating several others: slower perceived performance (no instant cached data), higher data consumption, faster battery drain, and a broken offline experience where every screen shows an error instead of previously loaded content.

The correct approach is to choose the appropriate fetch policy for each query based on how time-sensitive that data is. Don't apply a blanket policy across all queries.

Forgetting to Cancel Subscriptions

The Subscription widget manages its WebSocket connection automatically: it opens when the widget enters the tree and closes when the widget leaves.

But if you use the client's subscribe() method directly inside a Bloc or any long-lived object, you receive a Stream that you must manage yourself. Subscriptions that are never cancelled are memory leaks that accumulate silently with every navigation event:

class PostBloc extends Bloc {
  StreamSubscription? _commentSubscription;

  void startListeningToComments(String postId) {
    _commentSubscription = _repository
        .watchNewComments(postId)
        .listen((comment) => add(CommentReceived(comment)));
  }

  @override
  Future close() {
    _commentSubscription?.cancel(); // Always cancel before closing
    return super.close();
  }
}

Not Handling Partial GraphQL Results

A GraphQL response can carry both data and errors simultaneously. This is a partial result: some resolvers succeeded and some failed. If you check only result.hasException, you may miss GraphQL errors that accompanied successfully resolved data.

Always inspect both result.data and result.exception and decide explicitly how your UI should behave in each combination.

Mini End-to-End Example

Let's build a complete, runnable application to put everything in context. We'll use the GitHub GraphQL API so you can run this immediately without setting up your own server. The app fetches the authenticated user's repositories and allows starring and unstarring them, demonstrating queries, mutations, and optimistic UI together in a single working codebase.

Generate a GitHub personal access token at https://github.com/settings/tokens with at least read:user and repo scopes before running the example.

The GraphQL Client

// lib/graphql/client.dart

import 'package:flutter/material.dart';
import 'package:graphql_flutter/graphql_flutter.dart';

// Never hardcode tokens in production.
// Use flutter_secure_storage or an equivalent secure mechanism.
const _githubToken = 'YOUR_GITHUB_TOKEN_HERE';

ValueNotifier buildGitHubClient() {
  final httpLink = HttpLink('https://api.github.com/graphql');

  final authLink = AuthLink(
    getToken: () => 'Bearer $_githubToken',
  );

  return ValueNotifier(
    GraphQLClient(
      link: authLink.concat(httpLink),
      cache: GraphQLCache(store: HiveStore()),
    ),
  );
}

This file sets up a GraphQL client that our Flutter app will use to talk to GitHub’s GraphQL API.

It creates an HTTP connection to https://api.github.com/graphql, then adds an authentication layer using your GitHub token so every request includes a Bearer token.

These two parts are combined so requests are both authenticated and correctly sent to GitHub.

Finally, it enables caching using GraphQLCache with HiveStore, so data can be stored locally and reused instead of always fetching from the network.

In simple terms: it connects our app to GitHub, attaches our login token, and adds local caching for performance.

The Queries

// lib/graphql/queries/repo_queries.dart

const String fetchViewerReposQuery = r'''
  query FetchViewerRepos($count: Int!) {
    viewer {
      login
      name
      avatarUrl
      repositories(
        first: $count
        orderBy: { field: STARGAZERS, direction: DESC }
        ownerAffiliations: [OWNER]
      ) {
        nodes {
          id
          name
          description
          stargazerCount
          primaryLanguage {
            name
            color
          }
          viewerHasStarred
        }
      }
    }
  }
''';

This file defines a GraphQL query that fetches data from GitHub about the currently authenticated user and their repositories.

The query is named FetchViewerRepos and it takes one variable, $count, which controls how many repositories to return.

It starts by asking for the viewer, which represents the logged-in user. From the viewer, it retrieves basic profile information like login, name, and avatarUrl.

Then it fetches the user’s repositories, limited by the $count variable. The repositories are sorted by the number of stars in descending order, and it only includes repositories where the user is the owner.

For each repository, it requests:

id (used for identifying and caching),
name,
description,
stargazerCount (number of stars),
primaryLanguage (including its name and color),
viewerHasStarred (whether the current user has starred it).

In simple terms, this query is asking: “Give me the logged-in user’s profile and a list of their most popular repositories, along with key details for each one.”

The Mutations

// lib/graphql/mutations/repo_mutations.dart

const String addStarMutation = r'''
  mutation AddStar($repoId: ID!) {
    addStar(input: { starrableId: $repoId }) {
      starrable {
        ... on Repository {
          id
          stargazerCount
          viewerHasStarred
        }
      }
    }
  }
''';

const String removeStarMutation = r'''
  mutation RemoveStar($repoId: ID!) {
    removeStar(input: { starrableId: $repoId }) {
      starrable {
        ... on Repository {
          id
          stargazerCount
          viewerHasStarred
        }
      }
    }
  }
''';

This file defines two GraphQL mutations that let our app star and unstar repositories on GitHub.

The first mutation, addStarMutation, is used to star a repository. It takes a variable called $repoId, which is the unique ID of the repository. When executed, it calls addStar with that ID. The response returns the updated repository data, specifically:

the id,
the updated stargazerCount (number of stars),
and viewerHasStarred (which becomes true after starring).

The second mutation, removeStarMutation, does the opposite. It removes a star from a repository using the same $repoId. It calls removeStar, and the response again returns:

id,
updated stargazerCount,
and viewerHasStarred (which becomes false after unstarring).

Both mutations use a GraphQL concept called inline fragments (... on Repository) to ensure the returned data is specifically treated as a Repository type.

In simple terms: one mutation adds a star, the other removes it, and both return the updated repository state so your UI can update immediately.

The Entry Point

// lib/main.dart

import 'package:flutter/material.dart';
import 'package:graphql_flutter/graphql_flutter.dart';
import 'graphql/client.dart';
import 'screens/repos_screen.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await initHiveForFlutter();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return GraphQLProvider(
      client: buildGitHubClient(),
      child: MaterialApp(
        title: 'GitHub Repos',
        debugShowCheckedModeBanner: false,
        theme: ThemeData(
          colorScheme: ColorScheme.fromSeed(seedColor: Colors.indigo),
          useMaterial3: true,
        ),
        home: const ReposScreen(),
      ),
    );
  }
}

This is the entry point of our Flutter app, and it wires everything together.

The main() function first ensures Flutter is initialized with WidgetsFlutterBinding.ensureInitialized(), which is required before doing any async setup. Then it calls initHiveForFlutter(), which prepares Hive for local storage. This is needed because our GraphQL client uses Hive for caching. After that, it runs the app by calling runApp().

The MyApp widget sets up the app’s structure. The most important part here is the GraphQLProvider, which injects your GraphQL client (from buildGitHubClient()) into the entire widget tree. This allows any widget in the app to make GraphQL queries and mutations without manually passing the client around.

Inside the GraphQLProvider, you define a MaterialApp with basic app settings like the title, theme, and disabling the debug banner. The home screen is set to ReposScreen, which means that screen will be the first thing users see when the app launches.

The Repos Screen

// lib/screens/repos_screen.dart

import 'package:flutter/material.dart';
import 'package:graphql_flutter/graphql_flutter.dart';
import '../graphql/queries/repo_queries.dart';
import '../graphql/mutations/repo_mutations.dart';

class ReposScreen extends StatelessWidget {
  const ReposScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Query(
      options: QueryOptions(
        document: gql(fetchViewerReposQuery),
        variables: const {'count': 15},
        fetchPolicy: FetchPolicy.cacheAndNetwork,
      ),
      builder: (QueryResult result,
          {VoidCallback? refetch, FetchMore? fetchMore}) {
        if (result.isLoading && result.data == null) {
          return const Scaffold(
            body: Center(child: CircularProgressIndicator()),
          );
        }

        if (result.hasException) {
          return Scaffold(
            body: Center(
              child: Column(
                mainAxisSize: MainAxisSize.min,
                children: [
                  const Icon(Icons.error_outline,
                      size: 48, color: Colors.red),
                  const SizedBox(height: 12),
                  Text(
                    result.exception?.graphqlErrors.firstOrNull?.message
                        ?? 'An error occurred',
                    textAlign: TextAlign.center,
                  ),
                  const SizedBox(height: 16),
                  ElevatedButton(
                    onPressed: refetch,
                    child: const Text('Retry'),
                  ),
                ],
              ),
            ),
          );
        }

        final viewer =
            result.data?['viewer'] as Map?;
        final repos =
            (viewer?['repositories']?['nodes'] as List?)
                    ?.cast>() ??
                [];

        return Scaffold(
          appBar: AppBar(
            title: Row(
              children: [
                if (viewer?['avatarUrl'] != null)
                  CircleAvatar(
                    backgroundImage:
                        NetworkImage(viewer!['avatarUrl'] as String),
                    radius: 16,
                  ),
                const SizedBox(width: 8),
                Text(viewer?['name'] as String? ??
                    viewer?['login'] as String? ??
                    ''),
              ],
            ),
            // A subtle indicator that a background refresh is running
            bottom: result.isLoading
                ? const PreferredSize(
                    preferredSize: Size.fromHeight(2),
                    child: LinearProgressIndicator(),
                  )
                : null,
          ),
          body: RefreshIndicator(
            onRefresh: () async => refetch?.call(),
            child: ListView.separated(
              padding: const EdgeInsets.all(16),
              itemCount: repos.length,
              separatorBuilder: (_, __) => const SizedBox(height: 8),
              itemBuilder: (context, index) =>
                  RepoCard(repo: repos[index]),
            ),
          ),
        );
      },
    );
  }
}

class RepoCard extends StatelessWidget {
  final Map repo;

  const RepoCard({super.key, required this.repo});

  @override
  Widget build(BuildContext context) {
    final language =
        repo['primaryLanguage'] as Map?;
    final isStarred = repo['viewerHasStarred'] as bool? ?? false;
    final starCount = repo['stargazerCount'] as int? ?? 0;
    final repoId = repo['id'] as String;
    final mutationDoc = isStarred ? removeStarMutation : addStarMutation;
    final mutationKey = isStarred ? 'removeStar' : 'addStar';

    return Mutation(
      options: MutationOptions(
        document: gql(mutationDoc),
        // The mutation returns id, stargazerCount, and viewerHasStarred.
        // The cache normalizes the updated repository by id and broadcasts
        // the change to all widgets holding data for this repository.
        onError: (error) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
              content: Text(
                error?.graphqlErrors.firstOrNull?.message
                    ?? 'Action failed',
              ),
            ),
          );
        },
      ),
      builder: (RunMutation runMutation, QueryResult? mutationResult) {
        final isMutating = mutationResult?.isLoading ?? false;

        // Prefer values from the mutation result (including optimistic)
        // over the original query data so the UI reflects the latest state.
        final starrable =
            (mutationResult?.data?[mutationKey] as Map?)?[
                'starrable'] as Map?;

        final currentStarred =
            starrable?['viewerHasStarred'] as bool? ?? isStarred;
        final currentCount =
            starrable?['stargazerCount'] as int? ?? starCount;

        return Card(
          child: Padding(
            padding: const EdgeInsets.all(16),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Row(
                  children: [
                    Expanded(
                      child: Text(
                        repo['name'] as String? ?? '',
                        style: Theme.of(context)
                            .textTheme
                            .titleMedium
                            ?.copyWith(fontWeight: FontWeight.bold),
                      ),
                    ),
                    isMutating
                        ? const SizedBox(
                            width: 24,
                            height: 24,
                            child: CircularProgressIndicator(
                                strokeWidth: 2),
                          )
                        : IconButton(
                            onPressed: () => runMutation(
                              {'repoId': repoId},
                              // Optimistic result: update the UI instantly
                              // before the server responds.
                              optimisticResult: {
                                mutationKey: {
                                  'starrable': {
                                    '__typename': 'Repository',
                                    'id': repoId,
                                    'stargazerCount': isStarred
                                        ? starCount - 1
                                        : starCount + 1,
                                    'viewerHasStarred': !isStarred,
                                  }
                                }
                              },
                            ),
                            icon: Icon(
                              currentStarred
                                  ? Icons.star
                                  : Icons.star_border,
                              color: currentStarred
                                  ? Colors.amber
                                  : Colors.grey,
                            ),
                            tooltip:
                                currentStarred ? 'Unstar' : 'Star',
                          ),
                  ],
                ),
                if (repo['description'] != null)
                  Padding(
                    padding: const EdgeInsets.only(top: 4),
                    child: Text(
                      repo['description'] as String,
                      style: Theme.of(context).textTheme.bodySmall,
                      maxLines: 2,
                      overflow: TextOverflow.ellipsis,
                    ),
                  ),
                const SizedBox(height: 12),
                Row(
                  children: [
                    if (language != null) ...[
                      Container(
                        width: 12,
                        height: 12,
                        decoration: BoxDecoration(
                          shape: BoxShape.circle,
                          color: _parseColor(
                              language['color'] as String?),
                        ),
                      ),
                      const SizedBox(width: 4),
                      Text(
                        language['name'] as String? ?? '',
                        style: Theme.of(context).textTheme.bodySmall,
                      ),
                      const SizedBox(width: 16),
                    ],
                    const Icon(Icons.star, size: 14, color: Colors.amber),
                    const SizedBox(width: 4),
                    Text(
                      _formatCount(currentCount),
                      style: Theme.of(context).textTheme.bodySmall,
                    ),
                  ],
                ),
              ],
            ),
          ),
        );
      },
    );
  }

  Color _parseColor(String? hex) {
    if (hex == null) return Colors.grey;
    final hexValue = hex.replaceFirst('#', '');
    return Color(int.parse('FF$hexValue', radix: 16));
  }

  String _formatCount(int count) {
    if (count >= 1000) return '${(count / 1000).toStringAsFixed(1)}k';
    return count.toString();
  }
}

This code is building a GitHub-like repository screen in Flutter using graphql_flutter, and it relies heavily on GraphQL queries, mutations, and caching behavior to keep the UI in sync with remote data.

At the top level, the ReposScreen widget uses a Query widget from graphql_flutter to fetch data from a GraphQL endpoint. The query (fetchViewerReposQuery) requests the current user (the “viewer”) and a list of their repositories. It passes a variable (count: 15) to limit how many repositories are returned. The fetch policy cacheAndNetwork means it first tries to show cached data immediately, then updates it with fresh data from the network.

When the query is still loading and there's no cached data, the screen shows a loading spinner. If an error occurs, it displays an error message and a retry button that triggers refetch, which re-runs the query.

Once data is available, the screen extracts the viewer object and the list of repositories from the response. It then renders a Scaffold with an AppBar showing the user’s avatar and name, and a ListView that displays each repository using a RepoCard.

Each RepoCard represents a single repository and wraps its UI in a Mutation widget. This mutation handles starring and unstarring a repository. Depending on whether the repo is already starred (viewerHasStarred), it dynamically chooses either the “add star” or “remove star” mutation.

When the star button is pressed, the runMutation function is called with the repository ID. At the same time, an optimisticResult is provided so the UI updates immediately before the server responds. This is why the star count and icon change instantly, giving a smooth user experience.

The mutation also defines an onError handler that shows a SnackBar if something goes wrong during the mutation.

Inside the Mutation builder, the UI prefers data from the mutation result (if available) instead of the original query data. This ensures that once the mutation completes (or even during optimistic updates), the UI reflects the most recent state.

The repository card itself displays the repository name, optional description, primary language (with a colored dot), and star count. The star count is formatted to show values like “1.2k” for large numbers.

There's also a loading indicator on the star button while the mutation is in progress, so the user gets feedback that something is happening.

Finally, the key idea in this code is that GraphQL’s normalized cache is doing a lot of work behind the scenes. When a mutation updates a repository, the cache automatically updates all parts of the UI that depend on that repository’s id, keeping everything consistent without manually refreshing the entire list.

This complete, runnable application demonstrates every major concept in one cohesive codebase:

client setup with AuthLink and HiveStore,
a Query widget with proper loading, error, and data states with both pull-to-refresh and a background refresh indicator,
a Mutation widget inside each list item with optimistic UI that makes starring feel instant,
and the normalized cache propagating updates across the list automatically when a star operation completes.

Conclusion

GraphQL is not simply a different way to write APIs. It's a different philosophy about the relationship between a server and the clients that consume it.

The shift from server-driven to client-driven data fetching has real, measurable consequences: less bandwidth consumed, fewer network round trips, faster perceived screen loads, and more autonomy for frontend teams to build the UIs they need without waiting for backend changes.

For Flutter developers specifically, these benefits are amplified by the mobile context. Every saved byte is real bandwidth. Every eliminated round trip is real latency on the user's device. Every cache hit that avoids a re-fetch is real battery life preserved.

These aren't theoretical improvements. They show up in app metrics, in crash rates on poor connections, and in the reviews users leave when an app feels fast versus when it makes them wait.

The graphql_flutter package brings GraphQL into Flutter in a way that respects Flutter's reactive, widget-tree-based architecture. The Query, Mutation, and Subscription widgets fit naturally into how Flutter apps are built. The normalized cache, the composable link chain, and optimistic UI support provide the building blocks for the full complexity of production apps, not just toy examples.

Understanding the problem first is what makes everything else click. GraphQL's design decisions only make sense once you've felt the friction of over-fetching and the N+1 request problem.

Respecting the schema as the source of truth, rather than skimming it as documentation, gives you a development feedback loop that catches errors before they reach production. Embracing the normalized cache rather than fighting it with blanket network-only policies unlocks the reactive, fluid UX that separates great apps from merely functional ones. And structuring your codebase with a clean repository layer, combined with a proper state management solution, produces a system that stays maintainable as the product and the team grow.

GraphQL isn't the right tool for every project. Simple apps, small teams with tight timelines, and file-heavy workflows are all legitimate reasons to stay with REST. But for the right project, a data-intensive Flutter app with complex entity relationships, multiple screen types, and real-time requirements, GraphQL is an exceptionally strong choice.

With the foundations this handbook has built, you have everything you need to make that judgment confidently and to implement GraphQL correctly when it earns its place in your stack.

References

Official Package Documentation

graphql_flutter on pub.dev: The official package page, covering installation, Android build requirements, migration guides, and the complete widget API. https://pub.dev/packages/graphql\_flutter
graphql_flutter GitHub Repository: Source code, open issues, end-to-end working examples, and the full changelog. https://github.com/zino-app/graphql-flutter/tree/main/packages/graphql\_flutter
graphql Dart package README: In-depth documentation for the underlying Dart GraphQL client, covering the full link system, cache write strictness, direct cache access, AWS AppSync support, and file upload. https://github.com/zino-app/graphql-flutter/blob/main/packages/graphql/README.md
GraphQLCache API Docs: Detailed reference for cache configuration, normalization behavior, and write policies. https://pub.dev/documentation/graphql/latest/graphql/GraphQLCache-class.html
GraphQLDataProxy API Docs: Reference for the direct cache access API, covering readQuery, writeQuery, readFragment, and writeFragment. https://pub.dev/documentation/graphql/latest/graphql/GraphQLDataProxy-class.html

GraphQL Language and Specification

GraphQL Official Specification: The formal language specification maintained by the GraphQL Foundation. https://spec.graphql.org/
GraphQL.org Learn: The official introductory documentation for GraphQL concepts, written and maintained by the GraphQL Foundation. https://graphql.org/learn/
GraphQL: A Query Language for APIs: Meta's original technical introduction to GraphQL, explaining its design goals, the problems it was built to solve, and its fundamental philosophy. https://graphql.org/blog/graphql-a-query-language/

Tooling and Ecosystem

graphql_codegen: Code generation for graphql_flutter that produces type-safe hooks and option classes directly from your .graphql schema files. https://pub.dev/packages/graphql\_codegen
Altair GraphQL Client: A powerful desktop and browser-based GraphQL IDE for exploring and testing your API interactively. https://altair.sirmuel.design/
hive_ce: The Hive community edition package used by graphql_flutter for persistent on-disk cache storage. https://pub.dev/packages/hive\_ce

flutter_hooks: Required for the hooks-based API (useQuery, useMutation, useSubscription) in graphql_flutter. https://pub.dev/packages/flutter\_hooks
flutter_bloc: A widely used state management library that integrates cleanly with the repository pattern described in this guide. https://pub.dev/packages/flutter\_bloc
flutter_secure_storage: For securely storing authentication tokens on device rather than using insecure storage mechanisms. https://pub.dev/packages/flutter\_secure\_storage

Learning Resources

How to GraphQL: A comprehensive, free tutorial platform covering GraphQL from fundamentals through advanced topics, with examples in multiple languages and runtimes. https://www.howtographql.com/
GitHub GraphQL API Explorer: An in-browser GraphQL IDE for the GitHub API. Ideal for practicing queries and mutations against a real production GraphQL endpoint without needing your own server. https://docs.github.com/en/graphql/overview/explorer
GitHub GraphQL API Documentation: Complete reference for all types, queries, mutations, and subscriptions available in the GitHub GraphQL API, which this handbook's end-to-end example uses. https://docs.github.com/en/graphql

This handbook was written for graphql_flutter: ^5.3.0 with Flutter 3.x and Dart 3.x. API details may differ in earlier or later versions. Always refer to the official package documentation for the most current information.

How to Build a GraphQL API in Django

Udemezue John — Wed, 16 Apr 2025 13:22:37 +0000

If you're building an app with Django and thinking about using GraphQL, you're not alone.

REST has been the go-to for years, but GraphQL is quickly becoming a favourite option for developers who want more flexibility and less back-and-forth between frontend and backend.

I’ve spent a lot of time working with Django and playing around with different ways to make APIS smoother, and I get why people are switching to GraphQL.

You ask for exactly the data you need, and you get just that. No extra fluff, no multiple requests to stitch together data — it’s like ordering off a menu and getting exactly what you wanted, every single time.

So, if you’re curious about how to build a GraphQL API using Django, I’ve got you covered.

I’ll walk you through what GraphQL is, why it might be a better fit than REST in some cases, and how you can get started from scratch — even if you’re not a GraphQL expert (yet).

Here’s what we’ll cover:

What Is GraphQL, and Why Does It Matter?
What You’ll Need Before You Start
How to Build a GraphQL API in Django)
How to Add Mutations (Also Known As Writing Data)
Code Walkthrough: Creating a Post via Mutation in GraphQL)
How a Client Would Use This
Pros and Cons of Using GraphQL in Django
FAQs
What's Next?
Final Thoughts

What Is GraphQL, and Why Does It Matter?

GraphQL is a query language for APIs — and more importantly, it’s a runtime for fulfilling those queries with your data.

It was developed by Facebook in 2012 and made public in 2015. Since then, it's been used by companies like GitHub, Shopify, Twitter, and Pinterest.

Unlike REST, where you often have to make multiple requests to get all the data you need, GraphQL lets you fetch all your data in a single request.

This is a big deal, especially for mobile apps or slow networks where fewer requests mean better performance.

Let’s say you want a user’s name, profile picture, and their 3 most recent blog posts. With REST, you might need to hit 2-3 different endpoints. With GraphQL? One request, done.

It’s also great for frontend devs because they can shape the data they get back without waiting for backend devs to create new endpoints.

What You’ll Need Before You Start

Before jumping in, here’s what you should already have:

Basic knowledge of Django (models, views, and so on)
Python installed (3.8+ is best)
A Django project set up
pip or pipenv for package management

If you're starting fresh, you can spin up a new Django project with:

django-admin startproject myproject
cd myproject
python manage.py startapp myapp

How to Build a GraphQL API in Django

Let’s get into it.

1. Install Graphene-Django

Graphene is the most popular library for using GraphQL with Python. For Django specifically, there's a package called graphene-django.

You can install it like this:

pip install graphene-django

Then, add it to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    'graphene_django',
]

2. Add a Simple Model

Here’s a quick model to work with. In myapp/models.py:

from django.db import models

class Post(models.Model):
    title = models.CharField(max_length=100)
    content = models.TextField()
    published = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.title

Then run your migrations:

python manage.py makemigrations
python manage.py migrate

3. Create a Schema

In myapp/schema.py, start with:

import graphene
from graphene_django.types import DjangoObjectType
from .models import Post

class PostType(DjangoObjectType):
    class Meta:
        model = Post

class Query(graphene.ObjectType):
    all_posts = graphene.List(PostType)

    def resolve_all_posts(root, info):
        return Post.objects.all()

schema = graphene.Schema(query=Query)

Then, in your Django project settings, add:

GRAPHENE = {
    "SCHEMA": "myapp.schema.schema"
}

And finally, in your urls.py:

from django.urls import path
from graphene_django.views import GraphQLView
from django.views.decorators.csrf import csrf_exempt

urlpatterns = [
    path("graphql", csrf_exempt(GraphQLView.as_view(graphiql=True))),
]

Now, visit http://localhost:8000/graphql and try this query:

{
  allPosts {
    title
    content
    published
  }
}

Boom. You just queried your database using GraphQL.

Here is what your GraphQL playground should look like.

How to Add Mutations (Also Known As Writing Data)

GraphQL isn’t just for reading data. You can also create, update, and delete. Here’s how to add a mutation for creating a post:

In myapp/schema.py:

class CreatePost(graphene.Mutation):
    class Arguments:
        title = graphene.String(required=True)
        content = graphene.String(required=True)

    post = graphene.Field(PostType)

    def mutate(self, info, title, content):
        post = Post(title=title, content=content)
        post.save()
        return CreatePost(post=post)

class Mutation(graphene.ObjectType):
    create_post = CreatePost.Field()

schema = graphene.Schema(query=Query, mutation=Mutation)

Now, in the GraphiQL playground, you can run:

mutation {
  createPost(title: "My First Post", content: "Hello GraphQL!") {
    post {
      id
      title
    }
  }
}

Pretty clean, right?

Code Walkthrough: Creating a Post via Mutation in GraphQL

Let me walk you through the code, explain what it does, and how GraphQL makes it work.

Step 1: The `CreatePost` Mutation Class

class CreatePost(graphene.Mutation):
    class Arguments:
        title = graphene.String(required=True)
        content = graphene.String(required=True)

    post = graphene.Field(PostType)

    def mutate(self, info, title, content):
        post = Post(title=title, content=content)
        post.save()
        return CreatePost(post=post)

Here’s what’s going on in this part:

graphene.Mutation: This defines a custom mutation, which in GraphQL is how we modify server-side data (similar to POST, PUT, and DELETE in REST).
class Arguments: Think of this as the "input" part of the mutation. We're requiring a title and content, both as strings. These are what the client must provide when calling the mutation.
post = graphene.Field(PostType): This defines the return type of the mutation. In this case, once a post is created, we return it using a custom GraphQL type called PostType.
mutate(self, info, title, content): This method is called when the mutation is executed. Inside it:
- We create a new Post model instance.
- We save it to the database.
- We return the mutation result as an CreatePost object with the new post attached.
This keeps the logic tight, readable, and testable – a great example of clean API design.

Step 2: Wiring the Mutation into the Schema

class Mutation(graphene.ObjectType):
    create_post = CreatePost.Field()

This is where we register our mutation. In GraphQL, all operations (queries and mutations) must be part of the schema. By adding create_post to the Mutation class, we expose it to the GraphQL endpoint.

Step 3: The Final Schema

schema = graphene.Schema(query=Query, mutation=Mutation)

In this code,

We’re creating a new graphene.Schema.
We pass in a Query class (assumed to be defined elsewhere for read operations) and our Mutation class for write operations.

This is the GraphQL equivalent of wiring up Django's urls.py – it's what gets exposed to clients when they hit your /graphql/ endpoint.

How a Client Would Use This

A client (frontend or API testing tool like Insomnia/Postman) would send a mutation like this:

mutation {
  createPost(title: "GraphQL is Awesome", content: "Let's build APIs with it!") {
    post {
      id
      title
      content
    }
  }
}

And get a response like:

{
  "data": {
    "createPost": {
      "post": {
        "id": "1",
        "title": "GraphQL is Awesome",
        "content": "Let's build APIs with it!"
      }
    }
  }
}

Bonus: Why This Is Awesome for Developers

Frontend teams can now build forms and instantly see the structure of the response.
Backend devs define what’s allowed and handle only necessary logic.
No more over-fetching or under-fetching data — GraphQL gives you just what you ask for.
Easy to test, debug, and scale.

Make Sure You Have the Following in Place

Ensure you have graphene-django installed.
Add 'graphene_django' to your INSTALLED_APPS.
Wire up the schema in your Django project’s urls.py.

from django.urls import path
from graphene_django.views import GraphQLView
from myapp.schema import schema

urlpatterns = [
    path("graphql/", GraphQLView.as_view(graphiql=True, schema=schema)),
]

Pros and Cons of Using GraphQL in Django

Pros:

Flexible queries
Great for frontend devs
Fewer API calls
Strongly typed schema
Better performance on slower networks

Cons:

Slightly steeper learning curve
More setup than REST
Can be overkill for simple APIS

FAQs

Is GraphQL better than REST?

It depends. GraphQL gives you more control and flexibility, but REST is easier to cache and simpler to set up for small projects.

Is Graphene the only way to use GraphQL with Django?

Nope. You can also use Ariadne or Strawberry. But Graphene is the most mature and widely used right now.

Does GraphQL work well with Django REST Framework?

They can live side-by-side. If you already have a REST API and want to add GraphQL, you don’t need to throw anything away.

What’s Next?

Once you’ve got the basics down, you can:

Add authentication with JWT or sessions
Use Relay if you need pagination and filtering
Connect your GraphQL API to React, Vue, or any frontend

Final Thoughts

If you’ve been using Django for a while and want to give your API a little more power and flexibility, GraphQL is 100% worth checking out.

Further Resources

Orchestrating AWS Lambda with GraphQL and Apollo Connectors

Rob Walters — Tue, 25 Mar 2025 16:12:16 +0000

AWS Lambda is a computing service that enables you to run arbitrary code functions without needing to provision, manage, or scale servers. It’s often used in the logic tier of a multi-tier architecture to handle tasks such as processing files in S3 or performing CRUD operations on a database.

AWS also offers an API Gateway, allowing developers to invoke AWS Lambda functions, which provides enhanced security and performance features like rate limiting. But even with the API Gateway, you have to coordinate these microservices, as your client applications likely each have unique data needs. Data might need to be transformed, filtered, or combined before it is returned to the client.

These orchestration tasks can reduce your productivity and take time and effort away from solving the business problem your application is trying to solve.

Apollo GraphQL is an API orchestration layer that helps teams ship new features faster and more independently by composing any number of underlying services and data sources into a single endpoint. This allows clients on-demand access to precisely what the experience needs, regardless of the source of that data.

This article will teach you how to orchestrate AWS Lambda functions using Apollo GraphQL. Specifically, here’s what we will cover:

GraphQL Primer
Tutorial Overview
Prerequisites
Section 1: Create the AWS Resources
Section 2: Create an Apollo Connector
Section 3: How to Use Apollo Sandbox
Summary

GraphQL Primer

For those unfamiliar with GraphQL, here’s a primer that offers some background on the challenges GraphQL addresses and how data is typically managed through REST APIs in GraphQL before the emergence of Apollo Connectors. If you’re familiar with GraphQL, feel free to skip this section.

GraphQL is a query language for APIs. This query language and corresponding runtime enable clients to specify exactly the data they require, minimizing over-fetching and under-fetching.

In contrast to REST, which necessitates multiple endpoints for various data requirements, GraphQL streamlines queries into a single request, enhancing performance and reducing network latency.

GraphQL also uses a strongly typed schema. This improves API documentation and makes validation, early error detection, and immersive developer tooling easy.

To illustrate the difference between REST APIs and GraphQL, consider the following REST API call: /user/123

Response:

{
  "id": 123,
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "phone": "555-1234",
  "address": {
    "street": "123 Main St",
    "city": "Springfield",
    "state": "IL",
    "zip": "62704"
  },
  "createdAt": "2022-01-01T12:00:00Z",
  "updatedAt": "2022-05-15T14:30:00Z",
  "isAdmin": false
}

If you were only interested in the name and email, using REST would be a lot of data returned from the network to the client for no reason. Using GraphQL, the GraphQL query to return the name and email would be the following:

query {
  user(id: 123) {
    name
    email
  }
}

The result set is just the data the client needs:

{
  "data": {
    "user": {
      "name": "Alice Johnson",
      "email": "alice@example.com"
    }
  }
}

This is a simple example showing the benefit of not over-fetching data, but GraphQL has many other advantages. One of them is the separation between client and server. Since both parties leverage and respect the GraphQL type schema, both teams can operate more independently with the back end defining where the data resides and the front end only asking for data it needs.

So how does GraphQL know how to populate data for every field in your schema? It does this through resolvers. Resolvers can fetch data from a back-end databases or third-party API such as REST APIs, gRPC, and so on. These functions comprise procedural code compiled and maintained for each field in the schema. Thus, one field can have a resolver that queries a REST API and another can query a gRPC endpoint.

To illustrate resolvers, consider the example above. Let’s add a field, status, that queries a REST API to determine if the user is full-time, part-time, or terminated.

First we have defined our schema as:

type User {
  id: ID!
  name: String!
  email: String!
  status: String!  # Need this from an external REST API
}

type Query {
  user(id: ID!): User
}

The user query in this case will accept a user id and return a type User. The resolver function to support the data fetching resembles the following:

const resolvers = {
  Query: {
    user: async (_, { id }) => {
      // Fetch user details from one REST API
      const userResponse = await fetch(`https://api.company.com/users/${id}`);
      const userData = await userResponse.json();

      // Fetch employee status from another REST API
      const statusResponse = await fetch(`https://api.company.com/employees/${id}/status`);
      const statusData = await statusResponse.json();

      return {
        id: userData.id,
        name: userData.name,
        email: userData.email,
        status: statusData.status, // e.g., "Full-Time", "Part-Time", "Terminated"
      };
    },
  },
};

Notice that not only are there two fetches needed to obtain the information the query requires, but we also need to write procedural code and deploy it.

A better approach would be to declaratively specify to GraphQL where the REST API is located and what data to return. Apollo Connectors is the solution to this challenge, simplifying the process and allowing you to declaratively integrate REST API data without requiring code compilation and maintenance.

Now that you have a general idea of GraphQL and the challenges it addresses, let’s delve into the example we will build out.

Tutorial Overview

In this tutorial, you will create two AWS Lambda functions that return product information, which are described as follows:

Products Request:

POST /2015-03-31/functions/products/invocations

Response:

{
  "statusCode": 200,
  "body": [
    {
      "id": "RANQi6AZkUXCbZ",
      "name": "OG Olive Putter - Blade",
      "description": "The traditional Block in a blade shape is made from a solid block of Olive wood. The head weight is approximately 360 grams with the addition of pure tungsten weights. Paired with a walnut center-line and white accents colors.",
      "image": "https://keynote-strapi-production.up.railway.app/uploads/thumbnail_IMG_9102_3119483fac.png"
    },
    {
      "id": "RANYrWRy876AA5",
      "name": "Butter Knife Olive Putter- Blade",
      "description": "The traditional Block in a extremely thin blade shape (~1\") is made from a solid block of Olive wood. The head weight is approximately 330 grams with the addition of pure tungsten weights.",
      "image": "https://keynote-strapi-production.up.railway.app/uploads/thumbnail_IMG_9104_97c221e79c.png"
    },...

Product-price request:

POST: /2015-03-31/functions/product-price/invocations

Response:

{
  "default_price": 49900,
  "is_active": true,
  "currency": "usd",
  "billing_schema": "per_unit",
  "recurring": {
    "interval": 0,
    "interval_count": 3
  }
}

To expose these two lambda microservices, you need to create API Gateway triggers. This involves either setting up a distinct API Gateway for each lambda or consolidating them under one or a few API Gateway instances with specified routes for each lambda.

Creating a trigger may feel tedious and repetitive in a microservices setup. But there is an alternative available. You could directly invoke those functions via REST using the InvokeFunction permission assigned to an IAM user. This article will show you this method and guide you through function creation, necessary AWS IAM permissions, and configuring the Apollo Connector to invoke the function.

Prerequisites

To follow along in this tutorial, you will need to have a basic understanding of AWS Lambda functions as well as AWS security. You’ll also need access to the following:

An AWS account with permissions to create IAM Users and Policies
An Apollo GraphQL account, you can sign up for a free plan here.

We will also use the following tools:

VS Code: Microsoft VS Code is a free source code editor from Microsoft
Apollo Rover CLI: Rover is the command-line interface for managing and maintaining graphs
Apollo Studio: A web-based portal used for managing all aspects of your graph
Apollo Connectors Mapping Playground: A website that takes a JSON document and helps developers create the selection mapping used with Apollo Connectors

Section 1: Create the AWS Resources

First, let’s configure our AWS environment, starting with security. In our scenario, we will create an IAM User, “ConnectorUser,” with access to an AWS Policy, “ConnectorLambdaPolicy,” with the minimum permissions needed to access the AWS Lambda functions.

Note that you could create user groups and assign permission policies to those groups in a production environment. But for this article, we are reducing the number of administrative steps to focus on the core integration with GraphQL.

Step 1: Create an AWS Policy

To create a policy, navigate to IAM within the AWS Management console, then select “Policies” under Access Management. Click “Create Policy”. This will open the policy editor page, as shown below:

Choose the “Lambda” service and under the Access level select “InvokeFunction” from the Write drop down menu as shown below:

Under the Resources menu, you can choose either All ARNs or a specific option. It's a best practice to be as granular as possible when defining security configurations. In this example, let’s limit our selection to the “us-east-1” region by clicking on the “Specific” option and then “Add ARNs.” Enter “us-east-1” in the resource region and select “Any function name.”

With the policy created, we can assign an IAM user to that policy.

Step 2: Create the IAM User and Attach a Policy

Click on Users under “Access Management” then Create User. Provide a name for the user, “ConnectorUser”.

Next, select “Attach policies directly,” choose the policy we just created, “ConnectorLambdaPolicy,” and click “Create User.”

Step 3: Create AWS Lambda Functions

In your AWS console, create a new NodeJS AWS Lambda function, “products”.

Select “Node.JS” for the runtime then click “Create function”. Once created, paste in the the function code from this Gist.

Repeat this process, creating another function for, “product-price” and use the function code from this Gist.

Section 2: Create an Apollo Connector

In this section, we will install the Apollo Rover CLI tool, create an Apollo Studio free tier account, and clone the Apollo Connectors repository. If you already have an Apollo environment available, you can skip steps 1 and 2.

Step 1: Install Rover

Rover is the command-line interface for managing and maintaining graphs. It also provides a modern hot-reloading experience for developing and running your connectors locally. If you don’t have Rover installed, install it by following the steps here.

Step 2: Create an Apollo Studio Free Tier Account

Apollo Studio is a cloud-based management platform designed to explore, deliver, and collaborate on graphs. If you do not have an Apollo Studio account, create one on a free plan by navigating here.

Step 3: Clone the Apollo Connectors Repository

To help you start your first Apollo Connector, a GitHub repository provides sample connectors and a template script. When run, this script will create all the necessary files and configurations you need to begin.

Go ahead and clone the repository from here.

Note: While not required, I recommended using VS Code, as this repo leverages VS Code-specific settings files.

Step 4: Create a .env File

Before you run the Create Connectors template script, create a .env locally with a user API key from your Apollo Studio. You can create and obtain this key here. Populating this .env file will add this API key to the connector template you create in the next step.

Step 5: Create Your New Connector from a Template

Execute npm start and provide a location to create the connector template. You can use default values for the remaining questions.

This script will create all the necessary files to run a local Apollo GraphQL instance in the specified directory. Load the newly created connector using VS Code or your preferred code editor. You will return to this editor soon, but first, we need to obtain some access keys from AWS.

Step 6: Create an AWS Access Key

Since we connect to AWS using SigV4, we must create an AWS access key and enter the KEY values in the settings.json file. Return to the AWS IAM Console and select the ConnectorUser you created in Step 1. Create a new access key by clicking on “Create access key”.

You will be presented with multiple options as far as where the use of this key will originate. Since we are first running locally, select “Third-party service” and then continue the wizard until you are presented with the key and secret key as shown below:

Add the access key and secret access key to the settings.json file as “AWS_ACCESS_KEY_ID” and “AWS_SECRET_ACCESS_KEY” respectively.

You'll need to reload the window since VS Code only loads these files under the .vscode directory once.

Note: In this step, we saved the key to the settings.json file. While this is acceptable for development, consider saving environment variables in .env files.

Step 7: Configure the Graph

The supergraph.yaml file is used to define all the subgraphs that are part of this federation. Modify the supergraph.yaml file as follows:

federation_version: =2.10.0
subgraphs:
  awsconnector:
    routing_url: http://lambda
    schema:
      file: connector.graphql

Step 8: Configure Apollo Router

Apollo Router supports AWS SigV4 authentication. To configure the connector to use this, modify the router.yaml file and add an authentication section as follows:

authentication:
  connector:
    sources:
      awsconnector.lambda:   # subgraph name . connector source name
        aws_sig_v4:
          default_chain:
            region: "us-east-1"
            service_name: "lambda"

There are other AWS security configuration options available, including using assume role. The full documentation for subgraph authentication is available here.

Step 9: Build the connector

Now that we have configured the environment variables and authentication information, we are ready to build the connector. Open the connector.graphql file and erase the contents. Next, copy the following extend schema:

extend schema
  @link(
    url: "https://specs.apollo.dev/federation/v2.10"
    import: ["@key"]
  )
  @link(
    url: "https://specs.apollo.dev/connect/v0.1"
    import: ["@source", "@connect"]
  )

  @source(
    name: "lambda"
    http: { baseURL: "https://lambda.us-east-1.amazonaws.com" }
  )

Extend schema is used to link the Apollo Connectors directives into the current schema. In this article we are defining the base URL of our lambda function. If your REST API has HTTP headers that apply to all references of this source, such as Content-Length restrictions, you can add them here in the @source declaration. Next, let’s define the Product schema:

type Product {
  id: ID!
  name: String
  description: String
  image: String
  price: Price
    @connect(
      source: "lambda"
      http: {
        POST: "/2015-03-31/functions/product-price/invocations"
        body: """
        product_id: $this.id
        """
      }
      selection: """
      amount: default_price
      isActive: is_active
      currency
      recurringInterval: recurring.interval -> match(
        [0,"ONE_TIME"],
        [1,"DAILY"],
        [2,"MONTHLY"],
        [3,"ANNUALLY"],
      )
      recurringCount: recurring.interval_count
      """
    )
}

Notice our query Products has an @connect directive that defines, at a minimum, the source name. Here, you can add the HTTP-specific configuration you need for this field, such as Authorizations headers. In this scenario, since we only defined a baseUrl in the extend schema section, we need to put the specific URL for the InvokeFunction, which is /2015-03-31/functions/product-price/invocations.

The selection field allows you to transform and map values returned from the REST API using the mapping definition defined in the selection field. While a complete discussion of selection mapping is beyond the scope of this article, check out the documentation for a detailed look at Mapping GraphQL Responses. Apollo provides a free online tool that makes building mappings intuitive and fast.

Next, let’s define the Price schema and products Query.

type Price {
  amount: Float
  isActive: Boolean
  currency: String
  recurringInterval: RecurringInterval
  recurringCount: Int
}
enum RecurringInterval {
  ONE_TIME
  DAILY
  MONTHLY
  ANNUALLY
}

type Query {
  products: [Product]
    # https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html
    @connect(
      source: "lambda"
      http: { POST: "/2015-03-31/functions/products/invocations" }
      selection: """
      $.body {
        id
        name
        description
        image
      }
      """
    )
}

Now we're ready to run our connector and issue queries to our graph! The complete configuration script is available at this Gist.

Step 10: Run the Connector

If you're using VS Code, the repository includes a tasks.json file that adds a “rover dev” task, which launches Rover locally.

{
    "version": "2.0.0",
    "tasks": [{
        "label": "rover dev",
        "command": "rover", // Could be any other shell command
        "args": ["dev", "--supergraph-config","supergraph.yaml", "--router-config","router.yaml"],
        "type": "shell",
        "problemMatcher": [],
    }]
}

If you are not using VS Code, you can start your graph by executing rover dev –supergraph-config supergraph.yaml –router-config router.yaml from a terminal window.

If everything is configured correctly, you’ll see the following:

Section 3: How to Use Apollo Sandbox

The rover dev command you launched in the previous step configures a local Apollo Router instance for development mode. This mode makes it easy for developers to create, execute, and debug ad-hoc GraphQL queries using the Apollo Sandbox web portal. This portal is located at http://localhost:4000 by default.

Launch the portal and click on the products field. This will populate the Operation pane with all the available fields in the schema. In the operation pane, you can modify and build your GraphQL query. Clicking the Run button (which displays the query name, Products, in our example) will execute the query and show the results in the Response panel, as illustrated in the figure above.

In this example, you can see that data has been returned from our AWS Lambda function. To confirm, you can view the query plan by selecting "Query Plan” from the Response drop-down menu.

The query plan illustrates the orchestration of our two AWS Lambda functions that fetch product and product price data.

A helpful debugging feature is the Connectors Debugger, available in the drop-down as shown in the previous figure.

The Connection Debugger provides a comprehensive view of the HTTP request, including headers, body, response code, and the selection mapping used in the query. If you’re experiencing difficulties running queries, use this debugger – it will save you a lot of time.

Summary

In this article, you learned how to:

Set up AWS IAM User, Policies, and Lambda functions
Create an Apollo Connector to obtain data from an AWS Lambda function
Configure the Apollo Router
Execute and debug queries using Apollo Sandbox

Integrating AWS Lambda with Apollo Connectors offers a simplified, resolver-free method for incorporating cloud functions into your GraphQL API. By utilizing Apollo Connectors, you can declaratively link REST-based Lambda functions to your supergraph while ensuring secure authentication with AWS SigV4.

You can learn more about Apollo Connectors from the following resources:

Tutorial: GraphQL meets REST, with Apollo Connectors
Blog: Discover how Apollo Connectors integrate with Apollo Federation through insights from Apollo's Founder & CTO: REST API Orchestration with GraphQL.
Blog: Delve into the engineering journey behind Apollo Connectors and the process of their creation: Our Journey to Apollo Connectors
Webinar: Apollo Connectors GA Launch Webinar

How to Build a Pokemon App with GraphQL and Apollo

Segun Ajibola — Wed, 03 Apr 2024 12:28:07 +0000

Pokemon is a Japanese media franchise consisting of video games, animated series and films, a trading card game, and other related media.

In this blog, we will be building with a Pokemon GraphQL API that gives us data about different Pokemons.

We will be using Apollo and GraphQL to handle the data fetching, and React for building our front-end application.

No worries if you don't know these technologies, I will be walking you through the basics as you read on.

Prerequisites

You should have these in your computer to follow along:

Nodejs v18+
A code editor
A web browser

Let's create our React app.

React Application Setup

To create your React app, navigate to your terminal, and use the Command Prompt. Open your Command Prompt and choose your preferred location for creating your React project. Let's go with Desktop.

cd Desktop

The above command will navigate to your Desktop.

npm create vite@latest pokemon-app -- --template react

npm create vite@latest will start to build a new project using Vite. But we attached the name of our project (pokemon-app) and the technology or framework our app will be using (-- -- template react).

You can set another template like svelte, vanilla or vue and the project will be created using that framework. Read more about Vite on its official website.

After the Vite installation, run the following commands:

cd pokemon-app
npm install
npm run dev

We'll use the commands above to finish the React setup.

Run the first command, cd pokemon-app, to navigate to the pokeman-app folder.

Run code . to open the folder in your code editor.

modal displaying over VSCode to accept that you trust the authors of the files opened in VSCode

Mark the trust the author checkbox if that pops up.

Open your code editor's terminal. If you are running VSCode on Windows, the shortcut is `Ctrl + `` .

Run the other 2 commands in the terminal one after the other.

npm install

npm run dev

Your project should be running in the browser now.

We will be managing our data fetching using GraphQL and Apollo.

How to Use GraphQL and Apollo

GraphQL is a query language for APIs and a runtime for fulfilling queries with your existing data. It allows you to request only the data you need in your application and nothing more, making it very efficient and flexible.

Apollo is a state management library that allows you to manage local and remote data with GraphQL. It can be used to fetch, cache, and modify application data, all while automatically updating your UI.

Let's install the packages you need.

Installing Packages

Run the command below in your terminal to install the Apollo client.

npm install @apollo/client

Navigate to your main.jsx file and import these:

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App.jsx";
import {
  ApolloProvider,
  ApolloClient,
  InMemoryCache,
} from "@apollo/client";
import "./index.css";

You have imported React and ReactDOM for DOM manipulation.

ApolloClient is responsible for managing your application's data fetching and state management. It handles sending GraphQL queries and mutations to your GraphQL server and caching the results.

ApolloProvider will be used to wrap your React application to provide the Apollo Client instance to all your components so that your application can access data fetched through Apollo Client.

InMemoryCache is a cache implementation to store the results of GraphQL queries in memory for efficient access and retrieval.

You have also imported index.css to style your application.

How to Create an Apollo Client

const client = new ApolloClient({
  uri: "https://graphql-pokemon2.vercel.app/",
  cache: new InMemoryCache(),
});

The code above creates a new instance of ApolloClient with the some configurations:

uri: This specifies the URL of your GraphQL API endpoint. This is the endpoint where your Apollo Client will send GraphQL queries and mutations.
cache: This configures the cache implementation for Apollo Client to use an in-memory cache to access data and store the result of GraphQL queries, reducing the need to re-fetch data from the server.

You can now wrap your component with ApolloProvider:

ReactDOM.createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <ApolloProvider client={client}>
      <App />
    ApolloProvider>
  React.StrictMode>
);

Note that client props was also passed to provide your application with ApolloClient configuration.

Go to your App.jsx component and input this:

import React from "react";
import { PokemonsContainer } from "./components/PokemonsContainer";

export default function App() {
  return (
    <main>
      <PokemonsContainer />
    main>
  );
}

You imported React and PokemonsContainer will be created. The PokemonsContainer component was wrapped in main tag and will be rendered when the component is pasted in the DOM.

Let's create the PokemonsContainer component in a file located in components folder. That is:

📂 src/components/PokemonsContainer.jsx

Pokemons Container Component

import React from "react";
import { useQuery } from "@apollo/client";
import { Pokemon } from "../components/Pokemon";
import { GET_POKEMONS } from "../graphql/get-pokemons";

The useQuery from @apollo/client is used for executing queries in an Apollo application. To do that, useQuery() is called and a GraphQL query string is passed as a argument. When your component renders, useQuery returns an object from Apollo Client that contains loading, error, and data properties that you can use to render your UI.

Pokemon component was imported to render a user interface for a Pokemon, this will be built shortly.

GET_POKEMONS was also imported. This will contain a GraphQL query.

After importing the above functions, continue building your page.

export function PokemonsContainer() {
  const { loading, error, data } = useQuery(GET_POKEMONS, {
    variables: { first: 5 },
  });

  if (loading) return <p>Loading...p>;
  if (error) return <p>Error: {error.message}p>;

  const pokemons = data?.pokemons || [];
  return (
    <div className="container">
      {pokemons &&
        pokemons.map((pokemon) => (
          <Pokemon key={pokemon.id} pokemon={pokemon} />
        ))}
    div>
  );
}

As mentioned earlier, useQuery returns an object from Apollo Client that contains loading, error, and data properties. They are destructured here so you can access them in the page.

Notice that we're providing a configuration option (variables) to the useQuery hook. { variables: { first: 5 } } was also passed as the second argument. The variables option is an object that contains all of the variables we want to pass to our GraphQL query. In this case, we passed an object { first: 5 } to specify that we want the first five Pokemons.

If the query is still loading,

Loading...

is returned to signify the user while Error: {error.message} will be returned if there is an error.

The pokemons constant was created to hold the value of the Pokemons property of the data object. If data.pokemons is not available, the pokemons constant will be an empty array.

A div is returned with a classname of container which checks if pokemons is available and maps the array over the Pokemon component.

Let's create the Pokemon component:

📂src/components/Pokemon.jsx

Pokemon Component

import React from "react";

export function Pokemon({ pokemon }) {
  return (
    <div className="pokemon">
      <div className="pokemon__name">
        <p>{pokemon.name}p>
      div>
      <div className="pokemon__meta">
        <span>{pokemon.maxHP}span>
        <span>{pokemon.maxCP}span>
      div>
      <div className="pokemon__image">
        <img src={pokemon.image} alt={pokemon.name} />
      div>
      <div className="pokemon__attacks">
        {pokemon.attacks.special.slice(0, 3).map((attack) => (
          <span key={`${attack.name}-${attack.damage}`}>{attack.name}span>
        ))}
      div>
    div>
  );
}

The structure of an instance of a Pokemon is defined here with the classname for styling. The name, maxHP, maxCP, image and attacks array will be rendered.

Let's create the GET_POKEMONS GraphQL query.

📂src/graphql/get-pokemons

GraphQL Query

import gql from "graphql-tag";

export const GET_POKEMONS = gql`
  query pokemons($first: Int!) {
    pokemons(first: $first) {
      id
      name
      image
      maxHP
      maxCP
      attacks {
        special {
          name
          damage
        }
      }
    }
  }
`;

You imported gql from graphql-tag and created a GraphQL query named GET_POKEMONS.

The pokemons query function was wrapped in strings for the gql function to parse them into query documents.

$first: Int! means that your query is expecting a variable called first, which is an integer, and the ! symbol after the Int means that the variable is required.

Recall that we created the variables object in the PokemonsContainer component, it's here below.

 const { loading, error, data } = useQuery(GET_POKEMONS, {
   variables: { first: 5 },
 });

pokemons(first: $first) was also declared. $first will be assigned to 5 here (we passed in 9 in the above code snippet). Thus, the array will contain only 5 objects. Each object will contain id, name, image, maxHP, maxCP, and attacks object which will contain the special object containing name and damage.

The GraphQL server might contain more properties but will only return the properties listed above. That is one of the cool functionalities of GraqhQL – it gives you only the data you request for.

Styling our Application

Your index.css should contain this:

/* RESETS
=========================================== */
html {
  -webkit-box-sizing: border-box;
  box-sizing: border-box;
}

*,
*:before,
*:after {
  -webkit-box-sizing: inherit;
  box-sizing: inherit;
}

body {
  margin: 20px 0;
  padding: 0 20px;
  line-height: 1;
  font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
  color: #202020;
  background-color: #fbfbfb;
  font-smooth: always;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

/* POKEMON APPLICATION
=========================================== */
.container {
  display: flex;
  max-width: 80%;
  margin: auto;
  height: 100vh;
  justify-content: space-between;
  align-items: center;
  gap: 10px;
}

.container p {
  margin: 0;
}

.container .pokemon {
  width: 20%;
  background-color: #fff;
  background-clip: border-box;
  border: 1px solid rgba(0, 0, 0, 0.125);
  border-radius: 0.25rem;
  box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);
  overflow: hidden;
  /* margin: 5px; */
}

.container .pokemon__name {
  background-color: #ecd018;
  text-align: center;
  padding: 10px;
}

.container .pokemon__name p {
  text-transform: uppercase;
  font-weight: bold;
  color: white;
  letter-spacing: 4px;
  text-shadow: 0px 1px 2px rgba(0, 0, 0, 0.4);
}

.container .pokemon__image {
  padding: 20px;
  min-height: 300px;
  display: flex;
  align-items: center;
  justify-content: center;
}

.container .pokemon__image img {
  max-width: 100%;
  height: auto;
}

.container .pokemon__attacks {
  display: flex;
  padding-left: 10px;
  padding-right: 10px;
  justify-content: space-between;
}

.container .pokemon__attacks span {
  width: 32%;
  background-color: #f16820;
  border-radius: 3px;
  padding: 7px;
  font-weight: 700;
  color: #fff;
  padding-left: 10px;
  padding-right: 10px;
  font-size: 12px;
  margin-bottom: 10px;
  word-wrap: break-word;
  text-align: center;
  line-height: 15px;
}

.container .pokemon__meta {
  display: flex;
  justify-content: space-between;
  margin-top: 10px;
  padding: 0 10px;
}

.container .pokemon__meta span {
  color: white;
  text-shadow: 0px 1px 2px rgba(0, 0, 0, 0.4);
  background-color: #7bb7b7;
  font-weight: bold;
  margin: 0;
  padding: 5px 20px;
  border-radius: 5px;
}

All things done right, you should have this in your browser:

a picture showing the five pokemons data in the browser

You can get the GitHub code here: https://github.com/segunajibola/pokemon-graphql

You can also view the live site hosted on Vercel here: pokemonsapp.vercel.app

Check my portfolio of projects: segunajibola.com

Conclusion

That will be all. I hope you found value here as you learn more about the web.

If you enjoyed this article and want to see more content related to JavaScript and web development, then follow me here, Twitter (X) or connect on LinkedIn. I'd be happy to count you as one of my ever-growing group of awesome friends on the internet.

You can also join my WhatsApp developer community and OpenSource community of 330+ developers learning and building cool projects.

If you also want to support me, you can also buy me a cup of coffee.

Thanks and bye. 👋

API Integration Patterns – The Difference between REST, RPC, GraphQL, Polling, WebSockets and WebHooks

Daniel Adetunji — Mon, 09 Oct 2023 15:14:33 +0000

API stands for Application Programming Interface. The “I” in API is the key part that explains its purpose.

The interface is what the software presents to other humans or programs, allowing them to interact with it.

A good analogy for an interface is a remote control. Imagine you have a universal remote that can control your TV, lights, and fan.

Image showing a remote control and a TV, light fixture, and fan.

Let’s break down what a universal remote control can do:

The remote control has various buttons, each serving a different purpose. One button might change the channel, while another can dim the lights of the chandelier, and another can turn on the fan.
When you press a button, it sends a specific signal via infrared, bluetooth, or wifi to the object you are controlling, instructing it to perform a particular action.
The key thing about the remote is that it allows you to interact with the TV, chandelier, and the fan without understanding the internal workings of these objects. All that complexity is abstracted away from you. You simply press a button, and you get a response that you can observe straight away.

APIs work in a similar way.

APIs can have various endpoints, each designed to perform a specific action. One endpoint might retrieve data, while another updates or deletes it.
When you send a request to an endpoint, it communicates with the server using HTTP methods – GET, POST, PUT, DELETE to instruct it to perform a particular action (like retrieving, sending, updating, or deleting data).
The key thing about APIs, as with remote controls, is that APIs abstract away the inner workings of the server and the database behind the API. The API allows users, developers and applications to interact with a software application or platform without needing to understand its internal code or database structure. You simply send a request, the server processes it and provides a response.

This analogy only holds true for so long, as APIs are more complex than a remote control. But the basic principles of operation between an API and a universal remote are quite similar.

This article will explain API integration patterns, which can be split into two broad groups: Request-response (REST, RPC & GraphQL) and event driven APIs (Polling, WebSockets & WebHooks).

Request-Response Integration

In a request-response integration, the client initiates the action by sending a request to the server and then waits for a response.

Different patterns of the request-response integration exist, but at a high level, they all conform to the same rule of the client initiating a request and waiting for a response from the server.

1. REST

Rest stands for Representational State Transfer – the acronym is a combination of the first one or two letters from these three words. This is the simplest and most popular form of a request-response integration.

REST APIs use a stateless, client-server communication model, wherein each message contains all the information necessary to understand and process the message.

REST is all about resources. Resources are entities that the API exposes, which can be accessed and manipulated using URL paths.

To understand REST APIs, consider the following analogy. Imagine you go into a restaurant to order some food. The menu is extensive and items are categorically organised. Each item on the menu can be equated to a resource.

First, you call the waiter to get their attention, then you place an order. Each request receives a response, before you proceed with another request, like ordering a dish.

Restaurant analogy for REST API

In REST API terms, the client initiates requests to the server by specifying exactly what it wants using HTTP methods (such as GET, POST, PUT, DELETE) on specific URLs (the menu items). Each interaction is stateless, meaning that each request from the client to the server must contain all the information needed to understand and process the request.

The server then processes the request and returns the appropriate response – in our analogy, bringing the ordered item to the table.

Simple sequence diagram for REST API

2. RPC

RPC stands for Remote Procedure Call. Unlike REST APIs which are all about resources, RPC is all about actions. With RPC, the client executes a block of code on the server

Think of a restaurant without a menu. There is no dish you can request in this restaurant. Instead, you request a specific action to be performed by the restaurant.

Restaurant analogy for RPC

With a REST API, the guest would have simply asked for some fish and chips. With RPC, they have to give instructions on what they want the kitchen to prepare.

In the RPC pattern, the client calls a specific procedure on the server and waits for the result. The procedure to prepare and what gets prepared are tightly bound together. This might give the client very specific and tailored results, but lacks the flexibility and ease of use of REST.

There is a reason most restaurants use menus, instead of following the custom requests of their customers. This partly explains why RPC is a less popular integration pattern compared to REST.

3. GraphQL

With GraphQL, the client specifies exactly what data it needs, which can include specific fields from various resources. The server processes this query, retrieves the exact data, and returns it to the client.

This enables the client to have a high degree of flexibility and only retrieve exactly the data it needs. It also requires the server to be capable of handling more complex and unique queries.

In this way, GraphQL is a more customisable form of REST. You still deal with resources (unlike actions in RPC) but you can customise how you want the resource returned to you.

Think of a restaurant that allows you to customise your own dish by specifying exact quantities or ingredients you want.

Restaurant analogy for GraphQL

This may look similar to the RPC pattern, but notice that the customer is not saying how the food should be made, they're just customising their order by removing some ingredients (no salt) and reducing the number of some items (two pieces of fish instead of four).

One of the drawbacks of GraphQL is that it adds complexity to the API since the server needs to do additional processing to parse complex queries. This additional complexity would also apply to the restaurant analogy, since each order would need to be customised to the guest.

GraphQL has one clear benefit over REST and RPC. Since clients can specify exactly what they need, the response payload sizes are typically smaller, which means faster response times.

Event Driven Integration

This integration pattern is ideal for services with fast changing data.

Some of these integration patterns are also asynchronous and initiated by the server, unlike the request-response patterns which are synchronous and initiated by the client.

1. Polling

Let’s bring back the restaurant analogy. When you order food, it will take some time for it to be prepared.

You can get updates on your order by asking the waiter if it is ready yet. The more frequently you ask, the closer you will be to having real-time information about your order.

This, however, puts unnecessary strain on the waiter since they have to constantly check the status of your order and have them update you whenever you ask.

Restaurant analogy for polling

Polling is when the client continuously asks the server if there is new data available, with a set frequency. It's not efficient because many requests may return no new data, thus unnecessarily consuming resources.

The more frequently you poll (make requests) the closer the client gets to real-time communication with the server.

Simple sequence diagram showing polling in action

Most of the requests during polling are wasted, since they only return something useful to the client once there is a change on the server.

There is, however, another version of polling called long polling. With long polling, the waiter does not respond to the guest straightaway about the status of the order. Instead, the waiter only responds if there is an update.

Naturally, this only works if the guest and the waiter agree beforehand that a slow response from the waiter does not mean that the waiter is being rude and the guest is being ignored.

Restaurant analogy for long polling

With long polling, the server does not respond to the client immediately. It waits until something has changed before responding.

As long as the client and server agree that the server will hold on to the client’s request, and the connection between the client and server remains open, this pattern works and can be more efficient than simply polling.

These two assumptions for long polling may be unrealistic, though – the server can lose the client's request and/or the connection can be broken.

To address these limitations, long polling adds extra complexity to the process by requiring a directory of which server contains the connection to the client, which is used to send data to the client whenever the server is ready.

Standard polling on the other hand can remain stateless, making it more fault tolerant and scalable.

2. WebSockets

WebSockets provide a persistent, two-way communication channel between the client and server. Once a WebSocket connection is established, both parties can communicate freely, which enables real-time data flows and is more resource-efficient than polling.

Using the restaurant analogy again, a guest orders a meal and then establishes a dedicated communication channel with the waiter so they can freely communicate back and forth about updates or changes to the order until the meal is ready. This means the waiter can also initiate the communication with the guest, which is not the case for the other integration patterns mentioned so far.

Restaurant analogy for WebSockets

WebSockets are similar to long polling. They both avoid the wasteful requests of polling, but WebSockets have the added benefit of having a persistent connection between the client and the server.

WebSockets are ideal for fast, live streaming data, like real-time chat applications. The downside of WebSockets is that the persistent connection consumes bandwidth, so may not be ideal for mobile applications or in areas with poor connectivity

3. WebHooks

WebHooks allow the server to notify the client when there's new data available. The client registers a callback URL with the server and the server sends a message to that URL when there is data to send.

With WebHooks, the client sends requests as usual, but can also listen for and receive requests like a server.

Simple sequence diagram showing WebHooks in action

Using the restaurant analogy, when the guest orders a meal, they give the waiter a bell (analogous to the callback URL). The waiter goes to the kitchen and rings the bell as soon as the meal is ready. This allows the client to know, in real-time, about the progress of his order.

WebHooks are superior to polling because you get real-time updates from the server once something changes, without having to make frequent, wasteful requests to the server about that change.

They're also superior to long polling because long polling can consume more client and server resources as it involves keeping connections open, potentially resulting in many open connections.

Bringing it Together

In conclusion, APIs are crucial tools in software development, allowing users and applications to interact with software without understanding its inner workings.

They come in different integration patterns, such as REST, RPC, GraphQL, Polling, WebSockets, and WebHooks.

If you need a simple request-response integration, then REST, RPC or GraphQL could be ideal. For real-time or near-real-time applications, polling, WebScokets, or WebHooks are ideal.

As with any design problem, the right choice depends on the business case and what tradeoffs you are willing to tolerate.

How to Use GraphQL

Beau Carnes — Fri, 01 Sep 2023 20:47:21 +0000

GraphQL has been transforming the way that developers interact with APIs and data-driven applications. And there is a good chance you will need to know about it as a developer.

We just posted a full GraphQL course on the freeCodeCamp.org YouTube channel. In this comprehensive course, designed especially for those new to GraphQL, you will learn the knowledge and skills to create robust and efficient data-driven applications.

The Net Ninja created this course. He is a prolific technical course creator and is also one of the most viewed GraphQL instructors on the Internet. So he is the perfect person to teach this new GraphQL course.

GraphQL is a query language for your API, and a runtime for executing those queries by using a type system that you define for your data. Developed by Facebook in 2012 and released as an open-source project in 2015, GraphQL provides a more efficient, powerful, and flexible alternative to the traditional REST API. Instead of having multiple endpoints for different data needs, with GraphQL, you can request exactly what you need, all in one query. This can result in faster and more precise data retrieval.

This course will provide you with a solid foundation in GraphQL, allowing you to fully grasp its core principles and understand how it differs from traditional REST APIs.

Here are the sections in this course:

What is GraphQL?
Query Basics
Making a GraphQL Server (with Apollo)
Schema & Types
Resolver Functions
Query Variables
Related Data
Mutations (Adding & Deleting Data)
Update Mutation

By the time you complete this course, you'll be equipped with the practical skills needed to design, implement, and optimize data-driven applications using GraphQL. The Net Ninja's engaging teaching style and step-by-step tutorials ensure that you'll be able to follow along and apply what you've learned immediately.

Watch the full course on the freeCodeCamp.org YouTube channel (1.5 hour watch).

How to Avoid the N+1 Query Problem in GraphQL and REST APIs [with Benchmarks]

freeCodeCamp — Fri, 07 Jul 2023 17:59:59 +0000

By Mohamed Mayallo

The N+1 query problem is a performance issue you might face while building APIs, regardless of whether they're GraphQL or REST APIs.

In fact, this problem occurs when your application needs to return a set of data that includes related nested data – for example, a post that includes comments.

But how can you fix this problem? To avoid this issue, you should understand what is it and how it occurs.

So in this tutorial, you'll learn what the N+1 query problem is, why it is easy to fall into it, and how you can avoid it.

Before starting, it is good to know:

The examples in this article are just for the sake of simplicity.
SELECT * is very bad, and you should avoid it.
You should care about pagination if you’re working with large data sets.

You can find the examples in this article in this repo. Let's dive in.

Understanding the N+1 Query Problem

The N+1 problem occurs when your application needs to return a set of data that includes related data that exists in:

Another table.
Another database (in the case of microservices, for example)
Or even another third-party service.

In other words, you need to execute extra database queries or external requests to return the nested data.

If you are wondering about what the name means (N+1), follow the below example, which uses a single database:

Illustration of N+1 problem

As you can see, the relationship between Post and Comment is one-to-many, respectively.

So, if your application needs to return a list of posts and their related comments, you might end up with this code:

const posts = await rawSql('SELECT * FROM "Post"'); // Get all posts (1 database query)
for (const post in posts) {
    // For sure, you can replace the following query with an external request if you need to retrieve the post's comments from another service
    const comments = await rawSql(`SELECT * FROM "Comment" WHERE "post_id" = ${post.id}`); // Get all comments for every post (n database query for n posts)
    post.comments = comments;
}

So, you have executed N queries to retrieve every post’s comments and 1 query to retrieve all posts (N comments queries + 1 posts query).

But, why you should be aware of this problem?

Why Is the N+1 Query Problem a Serious Issue?

Here are some reasons why the N+1 query problem can cause serious performance issues in your application:

Your application makes a lot of database queries or external requests to retrieve a list of data like posts.
The more data your application retrieves, the slower your request is going to be and the more resources your application is going to consume.
A large data set might end up with notable network latency.
It is going to be challenging to scale the application to handle larger data sets.

On top of that, you are going to see the performance impact in numbers in the benchmarks section later in this article.

Now that you understand the N+1 query problem and its impact on your application, let’s introduce some effective ways you can avoid this problem.

Strategies to Avoid the N+1 Query Problem

Fortunately, there are a few simple strategies you can follow to avoid the N+1 query problem.

Let’s apply them to our previous example.

1) Eager Loading (Using SQL Joins, for example)

In this strategy, instead of returning the post’s comments separately for every post, you can use SQL Joins.

const postsAndComments = await rawSql(`
    SELECT * 
    FROM "Post"
    JOIN "Comment"
    ON "Comment"."post_id" = "Post"."post_id"
`);

When you're using this strategy, it's good to know that:

It is only one database query to return all posts and their nested comments.
You can't apply this strategy if you are consuming your data sets from a different database or service.

2) Batch Loading

In this strategy, your code should follow the below steps:

Execute one request to retrieve all posts.
Execute another request to load a batch of posts’ comments instead of loading every post’s comments separately.
Map every comment to its corresponding parent post.

Let’s jump into an example:

const posts = await rawSql('SELECT * FROM "Post"'), // 1- Retrieve all posts in one request
    postsIds = posts.map(post => post.id),
    postsComments = await rawSql(`SELECT * FROM "Comment" WHERE "post_id" IN (${postsIds})`); // 2- retrieve all posts’ comments in another request

for (const post in posts) { // 3- Map every comment to its parent post
    const comments = postsComments.filter(comment => comment.post_id === post.id);
    post.comments = comments;
}

As you see, in this strategy, there are just two requests: one to retrieve all posts and another one to retrieve their comments.

3) Caching

You may be familiar with caching and its impact on any application's performance.

You can implement caching on your client side or server side using Redis, Memcached, or any other similar tool. Wherever you can properly use caching, it significantly pushes your application's performance.

Let’s get back to our example and cache the posts’ comments in a Redis store.

    const posts = await rawSql('SELECT * FROM "Post"'),
        postsIds = posts.map(post => post.id),
        cachedPostsComments = getPostsCommentsFromRedis(postsIds);

for (const post in posts) {
    const comments = cachedPostsComments.filter(comment => comment.post_id === post.id);
    post.comments = comments;
}

As you might guess, you can cache the posts’ comments or even the posts themselves which significantly minimizes the load on databases.

4) Lazy Loading

In this strategy, you are distributing the responsibility between the server side and the client side.

You shouldn’t return all data at once from the server side. Instead, you prepare two endpoints for the client side like this:

GET /api/posts: Retrieves all posts.
GET /api/comments/:postId: Retrieves a post’s comments on demand.

And now, the data retrieval is up to the client side.

This strategy is very useful because:

It enables the client side to load the parent post first and display its content, and then load its related comments lazily. So users don't have to wait for the entire data set to be returned from the server side.
You have full control over sorting, filtering, pagination and so on over every endpoint.

The key point of this strategy is that it gets rid of nested data like comments and flattens all data sets in their own endpoint.

5) GraphQL Dataloader

As you might guess, this strategy works with GraphQL APIs.

Dataloader is a GraphQL utility that works by batching multiple database queries into one request. So, it uses the Batch Loading strategy under the hood.

Let’s jump into our example:

const DataLoader = require('dataloader');

// 1- GraphQL Schema Definition
const typeDefs = gql`
  type Post {
    post_id: ID!
        comments: [Comment]
  }

    type Comment {
        comment_id: ID!
    post_id: ID!
  }

  type Query {
    posts: [Post]
  }
`;

// 2- Resolve the GraphQL Schema
const resolvers = {
  Query: {
    posts: async () => {
      const posts = await rawSql('SELECT * FROM "Post"');
            return posts;
    }
  },

  Post: {
    comments: (post, args, { dataLoaders }) => {
      return dataLoaders.commentsLoader.load(post.id);
    }
  }
};

// 3- Define Dataloaders
const commentsBatchFunction = async postsIds => {
      const comments = await rawSql(`SELECT * FROM "Comment" WHERE "post_id" IN (${postsIds})`);
        const groupedComments = comments.reduce((tot, cur) => {
      if (!tot[cur.post_id]) {
        tot[cur.post_id] = [cur];
      } else {
        tot[cur.post_id].push(cur);
      }
      return tot;
    }, {});
        return postsIds.map((postId) => groupedComments[postId]);
    },
    createCommentsLoader = new DataLoader(commentsBatchFunction),
    createDataloaders = () => ({
        commentsLoader: createCommentsLoader()
    });

// 4- Inject Dataloaders in the GraphQL Context
const server = new ApolloServer({
    typeDefs,
    resolvers,
    context: () => {
    return {
      dataLoaders: createDataloaders(),
    }
  }
});

So how does it work? To get more detailed information, you can check out the documentation. But we'll go through the basics here.

The key point of the Dataloader is the Batch Function. Here, the batch function commentsBatchFunction takes an array of keys postsIds and returns a Promise which resolves to an array of values comments, [ [post1comment1, post1comment2], [post2comment1], ... ].

On top of that, the batch function has two constraints:

The size of the keys array postsIds must equal the values array comments. In other words, this expression must be true: postsIds.length === comments.length.
Each index in the keys array postsIds must correspond to the values array comments. So you might note that I looped over the postsIds to map each corresponding comment.

As a result, you can see that GraphQL Dataloader uses the second strategy (Batch Loading) under the hood.

Let’s get back to our example to walk through its implementation:

First, we defined the GraphQL schema.
Then we resolved the GraphQL schema. Keep in mind, if you resolved the comments in the Post type using this query await rawSql('SELECT * FROM "Comment" WHERE "post_id" = ' + post.id);, you’re going to fall into the N+1 query problem.
Next, we defined the comments batch function and then created the comments dataloader.
Finally, we injected dataloaders in the GraphQL Context to be able to use them in resolvers.

So, by using GraphQL Dataloader, if you have 10 posts and every post has 5 comments, you would end up with two queries – one to retrieve the 10 posts and another one to retrieve their comments.

Take a look at the following screenshot:

Illustration of process with and without Dataloader

Benchmarks About N+1 Query Problem

In this section, let’s compare each strategy in terms of performance.

N+1 in REST API	Eager Loading Strategy	Batch Loading Strategy	Caching Strategy	N+1 in GraphQL API	GraphQL Dataloader
2.139	0.065	0.048	0.019	2.44	0.397
2.147	0.081	0.068	0.024	2.38	0.483
2.152	0.062	0.065	0.035	2.67	0.372
2.17	0.053	0.047	0.031	2.71	0.377
2.181	0.052	0.069	0.031	2.38	0.364
2.14	0.076	0.043	0.017	2.53	0.346
2.321	0.073	0.045	0.018	2.60	0.451
2.13	0.061	0.06	0.015	2.35	0.369
2.149	0.064	0.04	0.015	2.65	0.368
2.361	0.065	0.045	0.016	2.54	0.424
2.190	0.065	0.053	0.022	2.525	0.395

Note that the results of the Cache strategy are coming just after caching the data set. The first query is ignored as caching is missed.

These results were generated from the following environment:

Seeded data: 1000 posts and 50 comments for every post.
CPU: AMD Ryzen 5 3600 6-Core Processor 3.60 GHz.
RAM: 32.0 GB.
OS: Windows 10 Pro.

To be able to retest these strategies in your environment, follow these steps:

Clone this repo.
Then run docker-compose up.
For GraphQL, open http://localhost:3000/graphql.
A query suffers from the N+1 problem: query only commentsWithNPlusOne in the Post type.
Dataloader strategy: query only commentsWithDataloader in the Post type.
For REST, follow these endpoints:
A query suffers from the N+1 problem: http://localhost:3000/api/postsWithNPlusOne.
Eager Loading strategy: http://localhost:3000/api/postsWithEagerLoading.
Batch Loading strategy: http://localhost:3000/api/postsWithBatchLoading.
Caching strategy: http://localhost:3000/api/postsWithCache.

My notes about these benchmarks:

These strategies are way too efficient.
You may notice that the slower strategy in REST, the Eager Loading strategy, is about 34 times faster than the N+1 query in the REST API.
The Dataloader strategy is about 6.4 times faster than the N+1 query in the GraphQL API.
If you compared the results of REST and GraphQL APIs, you may notice that REST is faster than GraphQL. I think this is because of the internal implementations of GraphQL, which makes sense.

Conclusion

In this article, you learned that the N+1 query problem is a performance issue you might encounter when working with APIs.

You then learned about some strategies you can follow to avoid this problem like:

Eager Loading using SQL Joins
Batch Loading by executing fewer requests and then mapping each corresponding item to its parent.
Caching using Redis
Dataloader in the GraphQL world.

Finally, we created some benchmarks about the N+1 query problem so we could see how efficiently these strategies improve our API performance.

Before you leave

If you found this article useful, you can check out some of my other articles on my personal blog as well.

Thanks a lot for staying with me up till this point. I hope you enjoy reading this article.

GraphQL Tutorial – How to Query The Rick and Morty API

Velda Kiara — Tue, 30 May 2023 18:07:33 +0000

I enjoy fictional books about greek gods, demigods, the oracle, and prophecies.

I am a huge fan of Rick Riordan's books. I recently came across Apollo's Trials, based on the greek god Apollo.

When I hear any mention of Apollo, my mind goes to the greek god who was the god of practically everything – including but not limited to music, poetry, art, prophecy, truth, archery, plague, healing, sun, and light.

Apollo client, just like the god Apollo, can do many things. For example, it lets you fetch and manage data from a GraphQL API on your client-side application. It is also simple, flexible, and compatible with any data source.

In this article, we will use the Apollo client to fetch data from the Rick and Morty API, named after the animated TV show with the same name. We will write a GraphQL query to fetch the data we need. The data will then be displayed using React.

Before we get started with the project, let's go over the use cases of GraphQL, and how it differs to REST APIs.

What Are The Use Cases of GraphQL?

GraphQL is used to build applications that require real-time data synchronization, like chat applications. It allows developers to fetch necessary data, reducing data transfer over the network, and improving application performance.

Microservices handle specific functionality or feature of the application, which poses a challenge to developers to work with multiple APIs individually.

GraphQL allows developers to create a single API that acts as a gateway to numerous microservices. It also improves performance since one query retrieves various microservices in a single request.

GraphQL provides a self-documenting schema, making it easy for developers to understand the data model and relationships between data. It also eases the process of creating, testing, and maintaining API, reducing time and cost.

Finally, GraphQL provides versioning capabilities to allow the evolution of the API schema without breaking existing clients. Versioning is possible since clients specify the exact data they need, making it easy to add new fields and remove depreciated ones without affecting existing clients.

What Are The Differences Between GraphQL and REST APIs?

With GraphQL, the client sends a query with the data it needs, and the server responds with that data alone. On the other hand, with REST APIs, the client sends a request to an endpoint, and the server responds with all the data/response related to the endpoint.

REST APIs are resource-based, where the endpoints represent data that can be accessed, created, updated, or deleted. On the other hand, GraphQL is graph-based, where each node represents a relationship between objects.

REST APIs, return data in a JSON (JavaScript Object Notation) or XML (Extensible Markup Language) format. At the same time, GraphQL allows the client to specify the data they need and responds with a JSON object matching the query.

GraphQL provides versioning to enable the API's evolution without disrupting the existing clients, while REST APIs create new endpoints for each version.

In some cases, REST APIs, can suffer from over-fetching or under-fetching, where the server may send much or little data. GraphQL accounts for this by allowing clients to request the data they need, thus reducing the amount of data transferred over a network.

Project Setup

Now that you are familiar with what you can do with GraphQL, let's start building the project.

Prerequisites

Fundamentals on React
Know about how APIs work and CSS (Cascading Style Sheets)

Dependencies Installation

Create a new React App named "rickandmorty".

 npm init [React](https://react.dev/)-app rickandmorty

npx create-[React](https://react.dev/)-app rickandmorty

Install Apollo Client and GraphQL. The code below installs two dependencies:

@apollo/client contains everything you need, like an in-memory cache, local state management, error handling, and a React-based view layer.
GraphQL provides logic for parsing the queries.

npm install @apollo/client [GraphQL](https://graphql.org/)

Rick & Morty API and Apollo Client Setup

Once the project is setup, we need to start using it in our files. Next, navigate to your index.js file using the cd command, and add the following code:

import [React](https://react.dev/)DOM from '[React](https://react.dev/)-dom/client';
import './index.css';
import App from './App';
import reportWebVitals from './reportWebVitals';
import { ApolloClient, InMemoryCache, ApolloProvider } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://rickandmortyapi.com/[GraphQL](https://graphql.org/)',
  cache: new InMemoryCache(),
});

const root = [React](https://react.dev/)DOM.createRoot(document.getElementById('root'));
root.render(
  <ApolloProvider client={client}>
  <App />
ApolloProvider>,
);

The code above creates an instance of the Apollo client with the URL (Uniform Resource Locator) of the Rick and Morty API GraphQL endpoint.

The App component is wrapped with the Apollo provider component to pass the client to all child components.

Query Implementation

Now, create a file called characters.js inside the src folder. The file will contain the query and any other functions that you want to add.

Inside the file, add the following code:

import { gql } from '@apollo/client';

export const GET_CHARACTERS = gql`
query Characters{
    characters{
      results {
        name
        species
        status
        type
        gender
        origin{name}
        location {name}
        image
      },
    },
  }
`;

In the code above, we import gql from the @apollo/client to define our query.

We create and export the variable GET_CHARACTERS as a string with capitalized letters. Capitalization is considered a best practice when defining queries in GraphQL. It is also considered a best practice to wrap strings with a template literal.

Objects in Javascript are collections or containers filled with key-value pairs. A key-value pair is referred to as a property.

The query, in our case, searches for the characters in Rick and Morty. It returns an object with the results property, which is an array of character objects.

Each character has properties like name, species, status, type, gender, and image- you can choose what you want to fetch 😉.

The other properties, origin and location, are objects with a name property for each character’s origin and location.

Character Function Definition

In the character.js file, add the following code below the GET_CHARACTERS query after modifying it as shown below:

import { useQuery, gql } from '@apollo/client';
import { useState } from "[React](https://react.dev/)";
import  { RandomCharacter } from './randomcharacters';
import './App.css';

export const GET_CHARACTERS = gql`
query Characters($name: String){
    characters ( filter: {name: $name}){
      results {
        name
        species
        status
        type
        gender
        origin{name}
        location {name}
        image
      },
    },
  }
`;

export function CharacterList() {
  const [searchTerm, setSearchTerm] = useState("");
  const {loading, error, data }   = useQuery(GET_CHARACTERS, {variables: {name: searchTerm}});
  const handleChange = (event) => {
    setSearchTerm(event.target.value);
  };
  return (
    <div>
      <input type="text" name="search" placeholder="search for Rick and Morty characters..." value={searchTerm} onChange={handleChange} className="search-input"  /> 
      {loading && (
            <div className="loader-container">
              <div className="loader">div>
            div>
       )}
      {error && <p> error p> }
      {data?.characters.results.length === 0 && (<>   <RandomCharacter/> )}
      {data && data.characters.results.map((character) => (
        <div className="card" key={character.name} style={{ backgroundImage: `url(${character.image})`,backgroundRepeat: 'no-repeat'}}> 
          <div className="info"> 
          <h2 className="h3"> {character.name}h2>
          <p> Status: {character.status}p>
          <p> Species: {character.species} p>
          <p> Type: {character.type}p>
          <p> Gender: {character.gender}p>
          <p> Origin: {character.origin.name}p>
          <p> Location: {character.location.name}p>
        div>
        div> 
      ))}
     
  );
}

The export function CharacterList() creates a function that is also exported to and can be used by other parts of the code.

The searchTerm variable initializes the search state to an empty string and creates a function setSearchTerm to update the value.

The useQuery hook from @apollo/client library fetches data from the API.

The query passes GET_CHARACTERS and a variable named searchTerm which is a variable to hold the character names being searched.

The handleChange variable sets searchTerm 's value to the input field's current value. The input field is the search bar that the user will use to search the names of the characters they want to view. The state is handled by handleChange.

We also need to account for issues with loading the site, as well as for any bugs that may occur.

loading is dynamically rendered with a spinner if loading is set to True. An error message is displayed if the error is set to True.

When the user is searching for a character that doesn't exist, we want to present a message and an alternate character they can find more information about – this is where the RandomCharacter comes in. We will define this later on. For now, let's keep it as is.

Once we fetch the data, we map the data.characters.results array to each character's card.

We also want to change the background of the cards to represent the character the information is for. The backgroundImage in the style property handles the dynamic change of the images. The rest of the items are displayed as text on the card.

How To Display Data

Now that we have a function working, we need to view what is being displayed in the browser, and whether we can make queries and get the data we need.

In your App.js file, add the following code:

function App() {
  return (
    <div>
    <h1 style={{ textAlign: 'center' }} >Rick and Morty Charactersh1>
    <CharacterList />
  div>
      );
    }

component displays the information about the characters we are getting from the API.

How to Randomize The Characters

Remember that we called the RandomCharacter component but we have yet to define it.

Create a file called randomcharacters.js in src and add the following code:

import { useQuery } from "@apollo/client";
import { gql } from '@apollo/client';
import { useState } from "[React](https://react.dev/)";
import './App.css';

export const GET_SINGLE_CHARACTER = gql`
query Character($id: ID!){
    character   (id: $id) {
        name
        species
        status
        type
        gender
        origin{name}
        location {name}
        image
      },
    },
`;

export const RandomCharacter = () => {
    const [randomNumber, setRandomNumber] = useState(Math.floor(Math.random() * 200));
    const { loading, error, data } = useQuery(GET_SINGLE_CHARACTER, {variables: {id: randomNumber } });


  return (
    <div>
       <p className="intro" >
         Sorry, we couldn't find that character 😞  
         <br/>
         <br/>
         How about this one instead? 😉 p>

      {/* {loading && <p>loading...p>} */}
      {loading && (
            <div className="loader-container">
              <div className="loader">div>
            div>
       )}
      {error && <p> error p> }
      {data && (<> 
        <div className="card" key={data.character.name} style={{ backgroundImage: `url(${data.character.image})`,backgroundRepeat: 'no-repeat'}}> 
        <div className="info"> 
          <h2 className="h3">{data.character.name}h2>
          <p>Status: {data.character.status}p>
          <p>Species: {data.character.species}p>
          <p>Type: {data.character.type}p>
          <p>Gender: {data.character.gender}p>
          <p>Origin: {data.character.origin.name}p>
          <p>Location: {data.character.location.name}p>
        div>
        div>
      
      )}
    
  );
};

We will replicate the query we created in the characters.js file, and rename it to GET_SINGLE_CHARACTER. Instead of looking for names, we will look for IDs.

We look for IDs because they are unique, and we want to randomize the characters that will be picked once a user does not get the character they are looking for.

randomNumber initializes state to the Math.floor function which generates a random number between 0 and 199 inclusive, using the Math.random() method and multiplying it by 200.

The Math.floor function rounds the result of the expression to the nearest integer. Every time the randomNumber needs to be updated the setRandomNumber function takes a new value as its argument and updates the state.

We have a message to alert the user that the character they are looking for is not found, but they can check out a new character.

The loading spinner is also implemented in this component, and the errors are there in case any issues occur. The images and cards are similar to the characters.js format since we want consistency with how everything looks.

How to Style the Display

We will use CSS to style how the cards will look, along with the search bar and the general page.

Having defined the functions and components, we will be adding className attributes to what needs to be styled.

Add the following code:

@import url(https://fonts.googleapis.com/css?family=Roboto:400,500,700);
body{
  background: navajowhite;
  font-family: Roboto, veranda;
  padding-bottom: 4em;
}
.card{
  position: relative;
  width: 22em;
  height: 30em;
  background-size: 22em 30em;
  box-shadow: 3px 3px 20px rgba(0,0,0,0.5);
  margin: auto;
  overflow: hidden;
  margin-bottom: 2em;
}
.card *{
  position: relative;
  z-index: 2;
}
.card:hover .info{
  bottom: -3em;
  opacity: 1;
  padding: 2px 1px;
  background-color: navajowhite;
}
.info{
  font-family: 'Droid Serif', serif;
  font-size: 1.2em;
  color: black;

  line-height: 1.1em;
  padding: 0 2em;
  position: relative;
  bottom: -4em;
  opacity: 0;
  background: transparent;
  transition: opacity 0.3s, bottom 0.3s;
  text-align: center;
}
/* search  bar*/
input[type="text"] {
  border: none;
  border-radius: 10px;
  background-color: #f2f2f2;
  padding: 10px;
  width: 500px;
  margin: 0 auto;
  display: block;
  font-size: 16px;
  font-family: 'Roboto', sans-serif;
  box-shadow: 2px 2px 5px rgba(0,0,0,0.2);
  margin-bottom: 2em;
}

input[type="text"]::placeholder {
  color: #999;
  font-style: italic;
}
/* no result */
.intro{
/* width: 10px; */
text-align: center;
margin: 0 auto;
color:black;
font-family: 'Droid Serif', serif;
font-size: 23px;
font-style: italic;
line-height: 20px;
padding-bottom: 15px;
}
/* spinner */
.loader-container {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100px;
}

.loader {
  border: 8px solid #f3f3f3; 
  border-top: 8px solid black;
  border-radius: 50%;
  width: 50px;
  height: 50px;
  animation: spin 1s linear infinite;
}

@keyframes spin {
  0% { transform: rotate(0deg); }
  100% { transform: rotate(360deg); }
}

Things to note:

The class .card represents what the card will look like.
The class .info represents the body text for the characters, such as the species.
The class .intro represents the text that appears if the character is not found.
The class .loader represents the spinner that shows before the results are displayed.

Your website should now look like this.

Conclusion

In this article, you learned how to use GraphQL queries with React, manage state using the useState hook, and style the different components of the web application.

May your keyboard be swift, your bugs be few, and your fun meter be off the charts as you code away!

The GraphQL API Handbook – How to Build, Test, Consume and Document GraphQL APIs

German Cocca — Tue, 02 May 2023 13:23:30 +0000

Hi everyone! In this tutorial we're going to take a deep dive into GraphQL APIs.

I recently wrote this article where I explained the main differences between common API types nowadays. And this tutorial aims to show you an example of how you can fully implement a GraphQL API.

We'll cover basic setup and architecture with Node and Apollo GraphQL, unit testing with Supertest, seeing how we can consume the API from a React front-end app using Apollo client and finally documenting the API using Apollo sandbox.

Keep in mind we won't go too deep into how each technology works. The goal here is to give you a general overview of how a GraphQL API works, how its pieces interact, and what a full implementation might consist of.

Let's go!

What is GraphQL?
Core GraphQL concepts
How to Build a GraphQL API with Node and Apollo GraphQL
How to Test a GraphQL API with Supertest
How to Consume a GraphQL API on a Front-end React App
How to Document a GraphQL API with Apollo sandbox
Wrapping up

What is GraphQL?

GraphQL is a query language and runtime for APIs that was developed by Facebook in 2012. It was released to the public in 2015 and has since gained popularity as an alternative to REST APIs.

GraphQL was originally developed by Facebook as a way to simplify data fetching for their mobile applications. They needed a way to make complex data requests from the server without causing performance issues or over-fetching data. GraphQL was born out of the need to solve these problems.

GraphQL was released as an open-source project in 2015 and has since gained popularity in the developer community. It is now supported by many development tools and frameworks, including Apollo, Prisma, and Hasura.

Main Characteristics:

Strongly Typed: GraphQL APIs are strongly typed, which means that each field has a specific data type. This makes it easier to validate and handle data on the client and server sides.
Query Language: GraphQL has its own query language that allows clients to specify exactly what data they need. This reduces over-fetching of data and improves performance.
Single Endpoint: GraphQL APIs have a single endpoint, which means that clients can fetch all the data they need from a single request.
Declarative: GraphQL APIs are declarative, which means that clients specify what they want, not how to get it. This allows for more efficient and flexible data fetching.
Schema-Driven: GraphQL APIs are schema-driven, which means that the schema defines the structure of the data and the available queries and mutations. This makes it easier for developers to understand and work with the API.

Pros:

Efficient Data Fetching: GraphQL APIs allow clients to fetch only the data they need, reducing over-fetching and improving performance.
Strongly Typed: GraphQL APIs are strongly typed, making it easier to validate and handle data.
Single Endpoint: GraphQL APIs have a single endpoint, reducing the complexity of the API and making it easier to work with.
Schema-Driven: GraphQL APIs are schema-driven, which makes it easier for developers to understand and work with the API.

Cons:

Complexity: GraphQL APIs can be more complex to set up and work with compared to REST APIs.
Caching: Caching can be more challenging with GraphQL APIs due to the flexible nature of the API.
Learning Curve: GraphQL requires a learning curve for both developers and clients, as it has its own query language and approach to data fetching.

Best for:

Efficient and flexible needs: GraphQL is well-suited for building applications that require efficient and flexible data fetching, such as mobile and web applications.
Complex data requirements: It is particularly useful in situations where there are complex data requirements and where over-fetching data can cause performance issues.

So to recap, GraphQL is a query language and runtime for APIs that provides efficient and flexible data fetching capabilities.

While it can be more complex to set up and work with compared to REST APIs, it offers benefits such as strongly typed data, single endpoints, and schema-driven development. It is well-suited for building applications with complex data requirements and where efficient data fetching is important.

Core GraphQL Concepts

Before we jump into building stuff, there are some core GraphQL concepts you need to understand in order to know what you're doing and how the code will work.

Object Types

In GraphQL, an Object Type is a complex type that represents a collection of fields. Object Types are used to define the structure of data that can be queried and mutated through a GraphQL API.

Each Object Type has a unique name and a set of fields, where each field has a name and a type. The type of a field can be a scalar type (such as Int, String, or Boolean), another Object Type, or a list of another type.

If you're familiar with Typescript and interfaces, this might ring a bell or two for you.

Here's an example of an Object Type that represents a "User" in a social media application:

type User {
  id: ID!
  name: String!
  email: String!
  friends: [User!]!
}

The ! sign means the field is mandatory.

In this example, the "User" Object Type has four fields: "id", "name", "email", and "friends". The "id" field has a type of ID, which is a built-in scalar type in GraphQL that represents a unique identifier. The "name" and "email" fields have a type of String, and the "friends" field has a type of a list of "User" Objects.

Here's another example of an Object Type that represents a "Book" in a library application:

type Book {
  id: ID!
  title: String!
  author: Author!
  genre: String!
  published: Int!
}

In this example, the "Book" Object Type has five fields: "id", "title", "author", "genre", and "published". The "id" field has a type of ID, the "title" and "genre" fields have a type of String, the "published" field has a type of Int, and the "author" field has a type of an "Author" Object.

Object Types can be used to define the structure of data that is returned from a query or mutation in a GraphQL API. For example, a query that returns a list of users might look like this:

query {
  users {
    id
    name
    email
    friends {
      id
      name
    }
  }
}

In this query, the "users" field returns a list of "User" Objects, and the query specifies which fields to include in the response.

Queries

In GraphQL, a query is a request for specific data from the server. The query specifies the shape of the data that the client wants to receive, and the server responds with the requested data in the same shape.

A query in GraphQL follows a similar structure to the shape of the data it expects to receive. It consists of a set of fields that correspond to the properties of the data the client wants to retrieve. Each field can also have arguments that modify the data returned.

Here's an example of a simple query in GraphQL:

query {
  user(id: "1") {
    name
    email
    age
  }
}

In this example, the query is requesting information about a user with the ID of "1". The fields specified in the query are "name", "email", and "age", which correspond to the properties of the user object.

The response from the server would be in the same shape as the query, with the requested data returned in the corresponding fields:

{
  "data": {
    "user": {
      "name": "John Doe",
      "email": "johndoe@example.com",
      "age": 25
    }
  }
}

Here, the server has returned the requested data about the user in the "name", "email", and "age" fields. The data is contained in a "data" object to differentiate it from any errors or other metadata that may be included in the response.

Mutations

In GraphQL, mutations are used to modify or create data on the server. Like queries, mutations specify the shape of the data being sent to and received from the server. The main difference is that while queries only read data, mutations can both read and write data.

Here's an example of a simple mutation in GraphQL:

mutation {
  createUser(name: "Jane Doe", email: "janedoe@example.com", age: 30) {
    id
    name
    email
    age
  }
}

In this example, the mutation is creating a new user on the server with the name "Jane Doe", email "janedoe@example.com", and age 30. The fields specified in the mutation are "id", "name", "email", and "age", which correspond to the properties of the user object.

The response from the server would be in the same shape as the mutation, with the newly created user data returned in the corresponding fields:

{
  "data": {
    "createUser": {
      "id": "123",
      "name": "Jane Doe",
      "email": "janedoe@example.com",
      "age": 30
    }
  }
}

Here, the server has returned the data about the newly created user in the "id", "name", "email", and "age" fields.

Mutations can also be used to update or delete data on the server. Here's an example of a mutation that updates a user's name:

mutation {
  updateUser(id: "123", name: "Jane Smith") {
    id
    name
    email
    age
  }
}

In this example, the mutation is updating the user with the ID of "123" to have the name "Jane Smith". The fields specified in the mutation are the same as in the previous example.

The response from the server would be the updated user data:

{
  "data": {
    "updateUser": {
      "id": "123",
      "name": "Jane Smith",
      "email": "janedoe@example.com",
      "age": 30
    }
  }
}

Mutations in GraphQL are designed to be composable, meaning that multiple mutations can be combined into a single request. This allows clients to perform complex operations with a single network round-trip.

Resolvers

In GraphQL, a resolver is a function responsible for fetching the data for a specific field defined in a GraphQL schema. Resolvers are the bridge between the schema and the data source. The resolver function receives four parameters: parent, args, context, and info.

parent: The parent object for the current field. In nested queries, it refers to the parent field's value.
args: The arguments passed to the current field. It is an object with key-value pairs of the argument names and their values.
context: An object shared across all resolvers for a particular request. It contains information about the request such as the currently authenticated user, database connection, etc.
info: Contains information about the query including the field name, alias, and the query document AST.

Here's an example of a resolver function for a User type's posts field:

const resolvers = {
  User: {
    posts: (parent, args, context, info) => {
      return getPostsByUserId(parent.id);
    },
  },
};

In this example, User is a GraphQL object type with a posts field. When the posts field is queried, the resolver function is called with the parent object User, any arguments passed, the context object, and query information. In this example, the resolver function calls a function getPostsByUserId to fetch the posts for the current user.

Resolvers can also be used for mutations to create, update or delete data. Here's an example of a resolver function for a createUser mutation:

const resolvers = {
  Mutation: {
    createUser: (parent, args, context, info) => {
      const user = { name: args.name, email: args.email };
      const createdUser = createUser(user);
      return createdUser;
    },
  },
};

In this example, Mutation is a GraphQL object type with a createUser mutation field. When the mutation is invoked, the resolver function is called with the parent object, arguments passed, context object, and query information. In this example, the resolver function calls a function createUser to create a new user with the given name and email, and returns the newly created user.

Schemas

In GraphQL, a schema is a blueprint that defines the structure of the data that can be queried in the API. It defines the available types, fields, and operations that can be performed on those types.

GraphQL schemas are written in the GraphQL Schema Definition Language (SDL), which uses a simple syntax to define the types and fields available in the API. The schema is typically defined in the server-side code and then used to validate and execute incoming queries.

Here's an example of a simple GraphQL schema definition:

type Book {
  id: ID!
  title: String!
  author: String!
  published: Int!
}

type Query {
  books: [Book!]!
  book(id: ID!): Book
}

type Mutation {
  addBook(title: String!, author: String!, published: Int!): Book!
  updateBook(id: ID!, title: String, author: String, published: Int): Book
  deleteBook(id: ID!): Book
}

In this schema, we have three types: Book, Query, and Mutation. The Book type has four fields: id, title, author, and published. The Query type has two fields: books and book, which can be used to retrieve a list of books or a specific book by ID, respectively. The Mutation type has three fields: addBook, updateBook, and deleteBook, which can be used to create, update, or delete books.

Note that each field has a type, which can be a built-in scalar type like String or Int, or a custom type like Book. The ! after a type indicates that the field is non-nullable, meaning it must always return a value (that is, it cannot be null).

TLDR and Comparison with Equivalent REST Concepts

Object Types: In GraphQL, Object Types are used to define the data that can be queried from an API, similar to how the response data model is defined in REST APIs. However, unlike REST, where data models are often defined in different formats (for example, JSON or XML), GraphQL Object Types are defined using a single language-agnostic syntax.
Queries: In GraphQL, queries are used to fetch data from an API, similar to HTTP GET requests in REST APIs. However, unlike REST APIs, where multiple requests may be required to fetch nested data, GraphQL queries can be used to fetch nested data in a single request.
Mutations: In GraphQL, mutations are used to modify data in an API, similar to HTTP POST, PUT, and DELETE requests in REST APIs. However, unlike REST APIs, where different endpoints may be required to perform different modifications, GraphQL mutations are performed through a single endpoint.
Resolvers: In GraphQL, resolvers are used to specify how to fetch data for a particular field in a query or mutation. Resolvers are similar to controller methods in REST APIs, which are used to fetch data from a database and return it as a response.
Schemas: In GraphQL, a schema is used to define the data that can be queried or mutated from an API. It specifies the types of data that can be requested, how they can be queried, and what mutations are allowed. In REST APIs, schemas are often defined using OpenAPI or Swagger, which specify the endpoints, request and response types, and other metadata for an API.

Overall, GraphQL and REST APIs differ in how they handle data fetching and modification.

REST APIs rely on multiple endpoints and HTTP methods to fetch and modify data, whereas GraphQL uses a single endpoint and queries/mutations to accomplish the same.

GraphQL's use of a single schema to define the data model of an API makes it easier to understand and maintain compared to REST APIs, which often require multiple documentation formats to describe the same data model.

How to Build a GraphQL API with Node and Apollo GraphQL

Our Tools

Node.js is an open-source, cross-platform, back-end JavaScript runtime environment that allows developers to execute JavaScript code outside of a web browser. It was created by Ryan Dahl in 2009 and has since become a popular choice for building web applications, APIs, and servers.

Node.js provides an event-driven, non-blocking I/O model that makes it lightweight and efficient, allowing it to handle large amounts of data with high performance. It also has a large and active community, with many libraries and modules available to help developers build their applications more quickly and easily.

Apollo GraphQL is a full-stack platform for building GraphQL APIs. It provides tools and libraries that simplify the process of building, managing, and consuming GraphQL APIs.

The core of the Apollo GraphQL platform is the Apollo Server, a lightweight and flexible server that makes it easy to build scalable and performant GraphQL APIs. The Apollo Server supports a wide range of data sources, including databases, REST APIs, and other services, making it easy to integrate with existing systems.

Apollo also provides a number of client libraries, including the Apollo Client for web and mobile, which simplifies the process of consuming GraphQL APIs. The Apollo Client makes it easy to query and mutate data, and provides advanced features like caching, optimistic UI, and real-time updates.

In addition to the Apollo Server and Apollo Client, Apollo provides a number of other tools and services, including a schema management platform, a GraphQL analytics service, and a set of developer tools for building and debugging GraphQL APIs.

If you're new to GraphQL or to Apollo itself, I really recommend you check out their docs. They're some of the best out there in my opinion.

Our Architecture

For this project we'll follow a layers architecture in our codebase. Layers architecture is about dividing concerns and responsibilities into different folders and files, and allowing direct communication only between certain folders and files.

The matter of how many layers should your project have, what names should each layer have, and what actions should it handle is all a matter of discussion. So let's see what I think is a good approach for our example.

Our application will have five different layers, which will be ordered in this way:

Application layers

The application layer will have the basic setup of our server and the connection to our schema and resolvers (the next layer).
The schema and resolvers layer will have the type definitions for our data and the connection to our queries and mutations (the next layer).
The queries and mutations layer will have the actual logic we want to perform in each of our queries and mutations and the connection to the model layer (the next layer, you get the idea...)
The model layer will hold the logic for interacting with our mock database.
Finally, the persistence layer is where our database will be.

An important thing to keep in mind is that in these kinds of architectures, there's a defined communication flow between the layers that has to be followed for it to make sense.

This means that a request first has to go through the first layer, then the second, then the third and so on. No request should skip layers because that would mess with the logic of the architecture and the benefits of organization and modularity it gives us.

If you'd like to know some other API architecture options, I recommend this software architecture article I wrote a while ago.

The Code

Before jumping to the code, let's mention what we'll actually build. We'll be building an API for a pet shelter business. This pet shelter needs to register the pets that are staying in the shelter, and for that we'll perform basic CRUD operations (create, read, update and delete).

We're using the exact same example we used in my article about fully implementing a REST API. If you're interested in reading that too, this should help to compare concepts between REST and GraphQL, and understand its differences and similarities. ;)

Now let's get this thing going. Create a new directory, hop in to it and start a new Node project by running npm init -y. For our GraphQL server we'll need two more dependencies, so run npm i @apollo/server and npm i graphql too.

App.js

In the root of your project, create an app.js file and drop this code in it:

import { ApolloServer } from '@apollo/server'
import { startStandaloneServer } from '@apollo/server/standalone'
import { typeDefs, resolvers } from './pets/index.js'

// The ApolloServer constructor requires two parameters: your schema
// definition and your set of resolvers.
const server = new ApolloServer({
    typeDefs,
    resolvers
})

// Passing an ApolloServer instance to the `startStandaloneServer` function:
//  1. creates an Express app
//  2. installs your ApolloServer instance as middleware
//  3. prepares your app to handle incoming requests
const { url } = await startStandaloneServer(server, {
    listen: { port: 4000 }
})

console.log(`🚀  Server ready at: ${url}`)

Here we're setting up our Apollo server, by passing it our typeDefs and resolvers (we'll explain those in a sec), and then starting the server in port 4000.

Next, go ahead and create this folder structure in your project:

Our folder structure

index.js

Within the index.js file put this code:

import { addPet, editPet, deletePet } from './mutations/pets.mutations.js'
import { listPets, getPet } from './queries/pets.queries.js'

// A schema is a collection of type definitions (hence "typeDefs")
// that together define the "shape" of queries that are executed against your data.
export const typeDefs = `#graphql
  # OBJECT TYPES
  # This "Pet" type defines the queryable fields for every pet in our data source.
  type Pet {
    id: ID!
    name: String!
    type: String!
    age: Int!
    breed: String!
  }

  # INPUT TYPES
  # Define the input objects for addPet and editPet mutations
  input PetToEdit {
    id: ID!
    name: String!
    type: String!
    age: Int!
    breed: String!
  }

  input PetToAdd {
    name: String!
    type: String!
    age: Int!
    breed: String!
  }

  # The "Query" type is special: it lists all of the available queries that
  # clients can execute, along with the return type for each. In this
  # case, the "pets" query returns an array of zero or more pets.
  # QUERY TYPES
  type Query {
    pets: [Pet],
    pet(id: ID!): Pet
  }

  # MUTATION TYPES
  type Mutation {
    addPet(petToAdd: PetToAdd!): Pet,
    editPet(petToEdit: PetToEdit!): Pet,
    deletePet(id: ID!): [Pet],
  }
`

export const resolvers = {
    // Resolvers for Queries
    Query: {
        pets: () => listPets(),
        pet: (_, { id }) => getPet(id)
    },

    // Resolvers for Mutations
    Mutation: {
        addPet: (_, { petToAdd }) => addPet(petToAdd),
        editPet: (_, { petToEdit }) => editPet(petToEdit),
        deletePet: (_, { id }) => deletePet(id)
    }
}

Here we have two main things: typeDefs and resolvers.

typeDefs defines the types for the data that can be queried in our API (in our case that's the pet object), as well as the input for queries/mutations (in our case that's PetToEdit and PetToAdd).

Lastly, it also defines the available queries and mutations for our API, declaring their names, as well as their input and return values. In our case we have two queries (pets and pet) and three mutations (addPet, editPet and deletePet).

resolvers contain the actual implementation of our queries and mutations types. Here we're declaring each query and mutation, and indicating what each should do. In our case, we're linking them with the queries/mutations we're importing from our queries/mutations layer.

pets.queries.js

In your pets.queries.js file drop this:

import { getItem, listItems } from '../models/pets.models.js'

export const getPet = id => {
    try {
        const resp = getItem(id)
        return resp
    } catch (err) {
        return err
    }
}

export const listPets = () => {
    try {
        const resp = listItems()
        return resp
    } catch (err) {
        return err
    }
}

As you can see, this file is very simple. It declares the functions that are imported in the index.js file and links them to the functions declared in the models layer.

pets.mutations.js

Same goes for our pets.mutations.js file, but with mutations now.

import { editItem, addItem, deleteItem } from '../models/pets.models.js'

export const addPet = petToAdd => {
    try {
        const resp = addItem(petToAdd)
        return resp
    } catch (err) {
        return err
    }
}

export const editPet = petToEdit => {
    try {
        const resp = editItem(petToEdit?.id, petToEdit)
        return resp
    } catch (err) {
        return err
    }
}

export const deletePet = id => {
    try {
        const resp = deleteItem(id)
        return resp
    } catch (err) {
        return err
    }
}

pets.models.js

Now go to the models folder and create a pets.models.js file with this code in it:

import db from '../../db/db.js'

export const getItem = id => {
    try {
        const pet = db?.pets?.filter(pet => pet?.id === parseInt(id))[0]
        return pet
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

export const listItems = () => {
    try {
        return db?.pets
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

export const editItem = (id, data) => {
    try {
        const index = db.pets.findIndex(pet => pet.id === parseInt(id))

        if (index === -1) throw new Error('Pet not found')
        else {
            data.id = parseInt(data.id)
            db.pets[index] = data
            return db.pets[index]
        }
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

export const addItem = data => {
    try {
        const newPet = { id: db.pets.length + 1, ...data }
        db.pets.push(newPet)
        return newPet
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

export const deleteItem = id => {
    try {
        // delete item from db
        const index = db.pets.findIndex(pet => pet.id === parseInt(id))

        if (index === -1) throw new Error('Pet not found')
        else {
            db.pets.splice(index, 1)
            return db.pets
        }
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

These are the functions responsible for interacting with our data layer (database) and returning the corresponding information to our controllers.

Database

We wont use a real database for this example. Instead we'll just use a simple array that will work just fine for example purposes, though our data will of course reset every time our server does.

In the root of our project, create a db folder and a db.js file with this code in it:

const db = {
    pets: [
        {
            id: 1,
            name: 'Rex',
            type: 'dog',
            age: 3,
            breed: 'labrador',
        },
        {
            id: 2,
            name: 'Fido',
            type: 'dog',
            age: 1,
            breed: 'poodle',
        },
        {
            id: 3,
            name: 'Mittens',
            type: 'cat',
            age: 2,
            breed: 'tabby',
        },
    ]
}

export default db

As you can see, our db object contains a pets property whose value is an array of objects, each object being a pet. For each pet, we store an id, name, type, age and breed.

Now go to your terminal and run nodemon app.js. You should see this message confirming your server is alive: 🚀 Server ready at: [http://localhost:4000/](http://localhost:4000/).

How to Test a GraphQL API with Supertest

Now that our server is up and running, let's implement a simple test suit to check if our queries and mutations behave as expected.

If you're not familiar with automated testing, I recommend you read this introductory article I wrote a while ago.

Our Tools

SuperTest is a JavaScript library that is used for testing HTTP servers or web applications that make HTTP requests. It provides a high-level abstraction for testing HTTP, allowing developers to send HTTP requests and make assertions about the responses received, making it easier to write automated tests for web applications.

SuperTest works with any JavaScript testing framework, such as Mocha or Jest, and can be used with any HTTP server or web application framework, such as Express.

SuperTest is built on top of the popular testing library Mocha, and uses the Chai assertion library to make assertions about the responses received. It provides an easy-to-use API for making HTTP requests, including support for authentication, headers, and request bodies.

SuperTest also allows developers to test the entire request/response cycle, including middleware and error handling, making it a powerful tool for testing web applications.

Overall, SuperTest is a valuable tool for developers who want to write automated tests for their web applications. It helps ensure that their applications are functioning correctly and that any changes they make to the codebase do not introduce new bugs or issues.

The Code

First we'll need to install some dependencies. To save up terminal commands, go to your package.json file and replace your devDependencies section with the code below. Then run npm install.

  "devDependencies": {
    "@babel/core": "^7.21.4",
    "@babel/preset-env": "^7.21.4",
    "babel-jest": "^29.5.0",
    "jest": "^29.5.0",
    "jest-babel": "^1.0.1",
    "nodemon": "^2.0.22",
    "supertest": "^6.3.3"
  }

Here we're installing the supertest and jest libraries, which we need for our tests to run, plus some babel stuff we need for our project to correctly identify which files are test files.

Still in your package.json, add this script:

  "scripts": {
    "test": "jest"
  },

To end with the boilerplate, in the root of your project, create a babel.config.cjs file and drop this code in it:

//babel.config.cjs
module.exports = {
    presets: [
      [
        '@babel/preset-env',
        {
          targets: {
            node: 'current',
          },
        },
      ],
    ],
  };

Now let's write some actual tests! Within your pets folder, create a pets.test.js file with this code in it:

import request from 'supertest'

const graphQLEndpoint = 'http://localhost:4000/'

describe('Get all pets', () => {
    const postData = {
        query: `query Pets {
            pets {
                id
                name
                type
                age
                breed
            }
        }`
    }

    test('returns all pets', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.pets).toEqual([
                    {
                        id: '1',
                        name: 'Rex',
                        type: 'dog',
                        age: 3,
                        breed: 'labrador'
                    },
                    {
                        id: '2',
                        name: 'Fido',
                        type: 'dog',
                        age: 1,
                        breed: 'poodle'
                    },
                    {
                        id: '3',
                        name: 'Mittens',
                        type: 'cat',
                        age: 2,
                        breed: 'tabby'
                    }
                ])
            })
    })
})

describe('Get pet detail', () => {
    const postData = {
        query: `query Pet {
            pet(id: 1) {
                id
                name
                type
                age
                breed
            }
        }`
    }

    test('Return pet detail information', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.pet).toEqual({
                    id: '1',
                    name: 'Rex',
                    type: 'dog',
                    age: 3,
                    breed: 'labrador'
                })
            })
    })
})

describe('Edit pet', () => {
    const postData = {
        query: `mutation EditPet($petToEdit: PetToEdit!) {
            editPet(petToEdit: $petToEdit) {
                id
                name
                type
                age
                breed
            }
        }`,
        variables: {
            petToEdit: {
                id: 1,
                name: 'Rexo',
                type: 'dogo',
                age: 4,
                breed: 'doberman'
            }
        }
    }

    test('Updates pet and returns it', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.editPet).toEqual({
                    id: '1',
                    name: 'Rexo',
                    type: 'dogo',
                    age: 4,
                    breed: 'doberman'
                })
            })
    })
})

describe('Add pet', () => {
    const postData = {
        query: `mutation AddPet($petToAdd: PetToAdd!) {
            addPet(petToAdd: $petToAdd) {
                id
                name
                type
                age
                breed
            }
        }`,
        variables: {
            petToAdd: {
                name: 'Salame',
                type: 'cat',
                age: 6,
                breed: 'pinky'
            }
        }
    }

    test('Adds new pet and returns the added item', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.addPet).toEqual({
                    id: '4',
                    name: 'Salame',
                    type: 'cat',
                    age: 6,
                    breed: 'pinky'
                })
            })
    })
})

describe('Delete pet', () => {
    const postData = {
        query: `mutation DeletePet {
            deletePet(id: 2) {
                id,
                name,
                type,
                age,
                breed
            }
        }`
    }

    test('Deletes given pet and returns updated list', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.deletePet).toEqual([
                    {
                        id: '1',
                        name: 'Rexo',
                        type: 'dogo',
                        age: 4,
                        breed: 'doberman'
                    },
                    {
                        id: '3',
                        name: 'Mittens',
                        type: 'cat',
                        age: 2,
                        breed: 'tabby'
                    },
                    {
                        id: '4',
                        name: 'Salame',
                        type: 'cat',
                        age: 6,
                        breed: 'pinky'
                    }
                ])
            })
    })
})

This a test suite for our GraphQL API. It uses the supertest library to make HTTP requests to the API endpoint (http://localhost:4000/) and verifies that the API responds correctly to various queries and mutations.

The code has five different test cases:

Get all pets: This test queries the API for all pets and verifies that the response matches an expected list of pets.
Get pet detail: This test queries the API for the details of a specific pet and verifies that the response matches the expected details for that pet.
Edit pet: This test performs a mutation to edit the details of a specific pet and verifies that the response matches the expected edited details for that pet.
Add pet: This test performs a mutation to add a new pet and verifies that the response matches the expected details for the newly added pet.
Delete pet: This test performs a mutation to delete a specific pet and verifies that the response matches the expected list of pets after the deletion.

Each test case includes a postData object that contains the GraphQL query or mutation to be sent to the API endpoint as well as any necessary variables.

The actual HTTP request is made using the request function from the supertest library, which sends a POST request to the API endpoint with the postData object in the request body. The response is then parsed as JSON and the test case verifies that the response matches the expected result using the expect function from the Jest testing framework.

Now go to your terminal, run npm test, and you should see all your tests passing:

> jest

 PASS  pets/pets.test.js
  Get all pets
    ✓ returns all pets (15 ms)
  Get pet detail
    ✓ Return pet detail information (2 ms)
  Edit pet
    ✓ Updates pet and returns it (1 ms)
  Add pet
    ✓ Adds new pet and returns the added item (1 ms)
  Delete pet
    ✓ Deletes given pet and returns updated list (1 ms)

Test Suites: 1 passed, 1 total
Tests:       5 passed, 5 total
Snapshots:   0 total
Time:        0.607 s, estimated 1 s
Ran all test suites.

How to Consume a GraphQL API on a Front-end React App

Now we know our server is running and behaving as expected. Let's see some more realistic example of how our API might be consumed by a front end app.

For this example, we'll use a React application, and Apollo client to send and process our requests.

Our Tools

React is a popular JavaScript library for building user interfaces. It allows developers to create reusable UI components and efficiently update and render them in response to changes in application state.

Regarding Apollo client, we've introduced it already.

Side comment – we're using Apollo client here since it's a very popular tool and it makes sense to use the same set of libraries both in front and back-end. If you're interested in other possible ways a GraphQL API can be consumed from a front-end React App, Reed Barger has a pretty cool article on this topic.

The Code

Let's create our React app by running yarn create vite and following the terminal prompts. Once that's done, run yarn add react-router-dom (which we'll use to setup basic routing in our app).

App.jsx

Put this code within your App.jsx file:

import { Suspense, lazy, useState } from 'react'
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom'
import './App.css'

const PetList = lazy(() => import('./pages/PetList'))
const PetDetail = lazy(() => import('./pages/PetDetail'))
const EditPet = lazy(() => import('./pages/EditPet'))
const AddPet = lazy(() => import('./pages/AddPet'))

function App() {
    const [petToEdit, setPetToEdit] = useState(null)

    return (
        <div className='App'>
            <Router>
                <h1>Pet shelterh1>

                <Routes>
                    <Route
                        path='/'
                        element={
                            <Suspense fallback={<>}>
                                <PetList />
                            Suspense>
                        }
                    />

                    <Route
                        path='/:petId'
                        element={
                            <Suspense fallback={<>}>
                                <PetDetail setPetToEdit={setPetToEdit} />
                            Suspense>
                        }
                    />

                    <Route
                        path='/:petId/edit'
                        element={
                            <Suspense fallback={<>}>
                                <EditPet petToEdit={petToEdit} />
                            Suspense>
                        }
                    />

                    <Route
                        path='/add'
                        element={
                            <Suspense fallback={<>}>
                                <AddPet />
                            Suspense>
                        }
                    />
                
            
        
    )
}

export default App

Here we're just defining our routes. We'll have 4 main routes in our app, each corresponding to a different view:

One to see the whole list of pets.
One to see the detail of a single pet.
One to edit a single pet.
One to add a new pet to the list.

Besides, we have a button to add a new pet and a state that will store the information of the pet we want to edit.

Next, create a pages directory with these files in it:

Folder structure

main.js

Before jumping into our pages, we have to set up the Apollo client library. Run yarn add @apollo/client and yarn add graphql to install the necessary dependencies.

The go to the main.js file and drop this code in it:

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './index.css'
import { ApolloClient, InMemoryCache, ApolloProvider } from '@apollo/client'

const client = new ApolloClient({
  uri: 'http://localhost:4000/',
  cache: new InMemoryCache(),
})

ReactDOM.createRoot(document.getElementById('root')).render(
  <ApolloProvider client={client}>
    <App />
  ApolloProvider>
)

Here we're initializing the ApolloClient, passing its constructor a configuration object with the uri and cache fields:

uri specifies the URL of our GraphQL server.
cache is an instance of InMemoryCache, which Apollo Client uses to cache query results after fetching them.

Then we wrap our App component with our ApolloProvider. This allows any component in our component tree to use the hooks provided by Apollo client, much like React Context works. ;)

Mutations and queries

In the root of your project, create this folder structure:

Folder structure

In these two files we'll declare the request bodies we'll use for our queries and mutations. I like to separate this into different files because it gives use a clear view of the different kinds of request we have in our app, and it also keeps our component's code cleaner.

In the queries.js file drop this:

import { gql } from '@apollo/client'

export const GET_PETS = gql`
    query Pets {
        pets {
            id
            name
            type
            breed
        }
    }
`

export const GET_PET = gql`
    query Pet($petId: ID!) {
        pet(id: $petId) {
            id
            name
            type
            age
            breed
        }
    }
`

And in the mutations.js file drop this:

import { gql } from '@apollo/client'

export const DELETE_PET = gql`
    mutation DeletePet($deletePetId: ID!) {
        deletePet(id: $deletePetId) {
            id
        }
    }
`

export const ADD_PET = gql`
    mutation AddPet($petToAdd: PetToAdd!) {
        addPet(petToAdd: $petToAdd) {
            id
            name
            type
            age
            breed
        }
    }
`

export const EDIT_PET = gql`
    mutation EditPet($petToEdit: PetToEdit!) {
        editPet(petToEdit: $petToEdit) {
            id
            name
            type
            age
            breed
        }
    }
`

As you can see, the syntax for queries and mutations is fairly similar. Request bodies are written in GraphQL query language, which is used to define the structure and data types of data that can be requested from a GraphQL API.

GraphQL Query Syntax:

export const GET_PETS = gql`
    query Pets {
        pets {
            id
            name
            type
            breed
        }
    }
`

This query is named Pets and it requests data from the pets field. The fields id, name, type, and breed are requested from each Pet object returned by the API.

In GraphQL, queries always start with the keyword query and are followed by the name of the query, if provided. The fields requested are enclosed in curly braces and can be nested to request data from related fields.

GraphQL Mutation Syntax:

export const ADD_PET = gql`
    mutation AddPet($petToAdd: PetToAdd!) {
        addPet(petToAdd: $petToAdd) {
            id
            name
            type
            age
            breed
        }
    }
`

This mutation is named AddPet and sends a new Pet object to be added to the API via the addPet mutation. The $petToAdd variable is defined as a required input of type PetToAdd. When the mutation is executed, the input variable will be passed in as an argument to the addPet mutation. The mutation then returns the id, name, type, age, and breed fields for the newly created Pet object.

In GraphQL, mutations always start with the keyword mutation and are followed by the name of the mutation, if provided. The fields requested in the mutation response are also enclosed in curly braces.

Note that both queries and mutations in GraphQL can accept variables as input, which are defined in the query or mutation body using a special syntax ($variableName: variableType!). These variables can be passed in when the query or mutation is executed, allowing for more dynamic and reusable queries and mutations.

PetList.jsx

Let's start with the file responsible for rendering the whole list of pets:

import { Link } from 'react-router-dom'
import { useQuery } from '@apollo/client'
import { GET_PETS } from '../api/queries'

function PetList() {
    const { loading, error, data } = useQuery(GET_PETS)

    return (
        <>
            <h2>Pet Listh2>

            <Link to='/add'>
                <button>Add new petbutton>
            Link>

            {loading && <p>Loading...p>}
            {error && <p>Error: {error.message}p>}

            {data?.pets?.map(pet => {
                return (
                    <div key={pet?.id}>
                        <p>
                            {pet?.name} - {pet?.type} - {pet?.breed}
                        p>

                        <Link to={`/${pet?.id}`}>
                            <button>Pet detailbutton>
                        Link>
                    div>
                )
            })}
        
    )
}

export default PetList

This code defines a React functional component called PetList that fetches a list of pets from a GraphQL API using the useQuery hook provided by the @apollo/client library. The query used to fetch the pets is defined in a separate file called queries.js, which exports a GraphQL query called GET_PETS.

The useQuery hook returns an object with three properties: loading, error, and data. These properties are destructured from the object and used to conditionally render different UI elements depending on the status of the API request.

If loading is true, a loading message is displayed on the screen. If error is defined, an error message is displayed with the specific error message returned by the API. If data is defined and contains an array of pets, each pet is displayed in a div with their name, type, and breed. Each pet div also contains a link to view more details about the pet.

The useQuery hook works by executing the GET_PETS query and returning the result as an object with the loading, error, and data properties. When the component first renders, loading is true while the query is being executed. If the query is successful, loading is false and data is populated with the results. If the query encounters an error, error is populated with the specific error message.

As you can see, managing requests with Apollo client is really nice and simple. And the hooks it provides, save us quite a bit of code normally used to execute requests, store it's response and handle errors.

Remember that to make calls to our server, we must have it up and running by running nodemon app.js in our server project terminal.

Just to show there's no weird magic going on here, if we go to our browser, open the dev tools and go to the network tab, we could see our app is making a POST request to our server endpoint. And that the payload is our request body in the form of a string.

The POST request

Request body

This means that if we wanted to, we could also consume our GraphQL API by using fetch, like following:

import { Link } from 'react-router-dom'
import { useEffect, useState } from 'react'

function PetList() {

    const [pets, setPets] = useState([])

    const getPets = () => {
        fetch('http://localhost:4000/', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                query: `
                query Pets {
                    pets {
                    id
                    name
                    type
                    breed
                    }
                }
                `
            })
        })
            .then(response => response.json())
            .then(data => setPets(data?.data?.pets))
            .catch(error => console.error(error))
    }

    useEffect(() => {
        getPets()
    }, [])

    return (
        <>
            <h2>Pet Listh2>

            <Link to='/add'>
                <button>Add new petbutton>
            Link>

            {pets?.map(pet => {
                return (
                    <div key={pet?.id}>
                        <p>
                            {pet?.name} - {pet?.type} - {pet?.breed}
                        p>

                        <Link to={`/${pet?.id}`}>
                            <button>Pet detailbutton>
                        Link>
                    div>
                )
            })}
        
    )
}

export default PetList

If you check your network tab again, you should see still the same POST request with the some request body.

Of course this approach is not very practical as it requires more lines of code to perform the same thing. But it's important to know that libraries like Apollo only give us a declarative API to work with and simplify our code. Beneath it all we're still working with regular HTTP requests.

PetDetail.jsx

Now let's go to the PetDetail.jsx file:

import { useEffect } from 'react'
import { useParams, Link } from 'react-router-dom'
import { useQuery, useMutation } from '@apollo/client'
import { GET_PET } from '../api/queries'
import { DELETE_PET } from '../api/mutations'

function PetDetail({ setPetToEdit }) {
    const { petId } = useParams()

    const { loading, error, data } = useQuery(GET_PET, {
        variables: { petId }
    })

    useEffect(() => {
        if (data && data?.pet) setPetToEdit(data?.pet)
    }, [data])

    const [deletePet, { loading: deleteLoading, error: deleteError, data: deleteData }] = useMutation(DELETE_PET, {
        variables: { deletePetId: petId }
    })

    useEffect(() => {
        if (deleteData && deleteData?.deletePet) window.location.href = '/'
    }, [deleteData])

    return (
        <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'center', aligniItems: 'center' }}>
            <h2>Pet Detailh2>

            <Link to='/'>
                <button>Back to listbutton>
            Link>

            {(loading || deleteLoading) && <p>Loading...p>}

            {error && <p>Error: {error.message}p>}
            {deleteError && <p>deleteError: {deleteError.message}p>}

            {data?.pet && (
                <>
                    <p>Pet name: {data?.pet?.name}p>
                    <p>Pet type: {data?.pet?.type}p>
                    <p>Pet age: {data?.pet?.age}p>
                    <p>Pet breed: {data?.pet?.breed}p>

                    <div style={{ display: 'flex', justifyContent: 'center', aligniItems: 'center' }}>
                        <Link to={`/${data?.pet?.id}/edit`}>
                            <button style={{ marginRight: 10 }}>Edit petbutton>
                        Link>

                        <button style={{ marginLeft: 10 }} onClick={() => deletePet()}>
                            Delete pet
                        button>
                    div>
                
            )}
        
    )
}

export default PetDetail

This component loads the detail info of the pet by executing a query in a very similar way than the previous component.

Moreover, it executes the mutation needed to delete the pet register. You can see that for this we're using the useMutation hook. It's quite similar to useQuery, but besides the loading, error and data values it also provides a function to execute our query after a given event.

You can see that for this mutation hook we're passing an object as second parameter, containing the variables this mutation requires. In this case, it's the id of the pet register we want to delete.

const [deletePet, { loading: deleteLoading, error: deleteError, data: deleteData }] = useMutation(DELETE_PET, {
    variables: { deletePetId: petId }
})

Remember that when we declared our mutation in mutations.js we had already declared the variables this mutation would use.

export const DELETE_PET = gql`
    mutation DeletePet($deletePetId: ID!) {
        deletePet(id: $deletePetId) {
            id
        }
    }
`

AddPet.jsx

This is the file responsible for adding a new pet to our register:

import React, { useState, useEffect } from 'react'
import { Link } from 'react-router-dom'
import { useMutation } from '@apollo/client'
import { ADD_PET } from '../api/mutations'

function AddPet() {
    const [petName, setPetName] = useState()
    const [petType, setPetType] = useState()
    const [petAge, setPetAge] = useState()
    const [petBreed, setPetBreed] = useState()

    const [addPet, { loading, error, data }] = useMutation(ADD_PET, {
        variables: {
            petToAdd: {
                name: petName,
                type: petType,
                age: parseInt(petAge),
                breed: petBreed
            }
        }
    })

    useEffect(() => {
        if (data && data?.addPet) window.location.href = `/${data?.addPet?.id}`
    }, [data])

    return (
        <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'center', aligniItems: 'center' }}>
            <h2>Add Peth2>

            <Link to='/'>
                <button>Back to listbutton>
            Link>

            {loading || error ? (
                <>
                    {loading && <p>Loading...p>}
                    {error && <p>Error: {error.message}p>}
                
            ) : (
                <>
                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet namelabel>
                        <input type='text' value={petName} onChange={e => setPetName(e.target.value)} />
                    div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet typelabel>
                        <input type='text' value={petType} onChange={e => setPetType(e.target.value)} />
                    div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet agelabel>
                        <input type='text' value={petAge} onChange={e => setPetAge(e.target.value)} />
                    div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet breedlabel>
                        <input type='text' value={petBreed} onChange={e => setPetBreed(e.target.value)} />
                    div>

                    <button
                        style={{ marginTop: 30 }}
                        disabled={!petName || !petType || !petAge || !petBreed}
                        onClick={() => addPet()}
                    >
                        Add pet
                    button>
                
            )}
        
    )
}

export default AddPet

Here we have a component that loads a form to add a new pet and performs a mutation when the data is sent. It accepts the new pet info as parameter, in a similar way that the deletePet mutation accepted the pet id.

EditPet.jsx

Finally, the file responsible for editing a pet register:

import React, { useState, useEffect } from 'react'
import { Link } from 'react-router-dom'
import { useMutation } from '@apollo/client'
import { EDIT_PET } from '../api/mutations'

function EditPet({ petToEdit }) {
    const [petName, setPetName] = useState(petToEdit?.name)
    const [petType, setPetType] = useState(petToEdit?.type)
    const [petAge, setPetAge] = useState(petToEdit?.age)
    const [petBreed, setPetBreed] = useState(petToEdit?.breed)

    const [editPet, { loading, error, data }] = useMutation(EDIT_PET, {
        variables: {
            petToEdit: {
                id: parseInt(petToEdit.id),
                name: petName,
                type: petType,
                age: parseInt(petAge),
                breed: petBreed
            }
        }
    })

    useEffect(() => {
        if (data && data?.editPet?.id) window.location.href = `/${data?.editPet?.id}`
    }, [data])

    return (
        <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'center', aligniItems: 'center' }}>
            <h2>Edit Peth2>

            <Link to='/'>
                <button>Back to listbutton>
            Link>

            {loading || error ? (
                <>
                    {loading && <p>Loading...p>}
                    {error && <p>Error: {error.message}p>}
                
            ) : (
                <>
                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet namelabel>
                        <input type='text' value={petName} onChange={e => setPetName(e.target.value)} />
                    div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet typelabel>
                        <input type='text' value={petType} onChange={e => setPetType(e.target.value)} />
                    div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet agelabel>
                        <input type='text' value={petAge} onChange={e => setPetAge(e.target.value)} />
                    div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet breedlabel>
                        <input type='text' value={petBreed} onChange={e => setPetBreed(e.target.value)} />
                    div>

                    <button
                        style={{ marginTop: 30 }}
                        disabled={!petName || !petType || !petAge || !petBreed}
                        onClick={() => editPet()}
                    >
                        Save changes
                    button>
                
            )}
        
    )
}

export default EditPet

Last, we have a component to edit a pet register through a form. It performs a mutation when the data is sent, and as parameters it accepts the new pet info.

And that's it! We're using all of our API queries and mutations in our front end app. =)

How to Document a GraphQL API with Apollo Sandbox

One of Apollo's coolest features is that it comes with a built-in sandbox you can use to test and document your API.

Apollo Sandbox is a web-based GraphQL IDE that provides a sandbox environment for testing GraphQL queries, mutations, and subscriptions. It is a free, online tool provided by Apollo that allows you to interact with your GraphQL API and explore its schema, data, and capabilities.

Here are some of the main features of Apollo Sandbox:

Query Editor: A feature-rich GraphQL query editor that provides syntax highlighting, autocompletion, validation, and error highlighting.
Schema Explorer: A graphical interface that allows you to explore your GraphQL schema and see its types, fields, and relationships.
Mocking: Apollo Sandbox allows you to easily generate mock data based on your schema, which is useful for testing your queries and mutations without connecting to a real data source.
Collaboration: You can share your sandbox with others, collaborate on queries, and see real-time changes.
Documentation: You can add documentation to your schema and query results to help others understand your API.

To use our sandbox, simply open your browser at http://localhost:4000/. You should see something like this:

Apollo sandbox

From here you can see the API data schema and available mutations and queries, and also execute them and see how your API responds. For example, by executing the pets query, we can see that response on the right side panel.

Executing a query

If you hop on to the schema section you could see a whole detail of the available queries, mutations object and input types in our API.

The schema section

Apollo sandbox is a great tool that can be used both as self-documentation for our API and a great development and testing tool.

Wrapping Up

Well everyone, as always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

Different Types of APIs – SOAP vs REST vs GraphQL

German Cocca — Tue, 07 Mar 2023 23:24:27 +0000

Hi everyone! In this article we're going to take a good look at APIs, a core concept in modern software development.

We're going to talk about the main kinds of APIs used nowadays (SOAP, REST and GraphQL), their characteristics, pros and cons, and situations in which each of them might be more beneficial.

Let's go! 🙃

How SOAP APIs Work
- About XML
- How to Consume a SOAP API
How REST APIs Work
- How to Consume a REST API
How GraphQL APIs work
- How to Consume a GraphQL API
Wrapping Up

Intro

In a recent article I talked briefly about two very important concepts in modern software development: the client-server model and APIs.

Client-server is a model that structures the tasks or workloads of an application between a resource or service provider (server) and a service or resource requester (client).

Put simply, the client is the application that requests some kind of information or performs actions, and the server is the program that sends information or performs actions according to what the client does.

Most applications nowadays use a client-server model. The most important concept to remember about it is that clients request resources or services that the server performs. The way in which these two parts usually communicate is through an API (application programming interface).

An API is nothing more than a set of defined rules that establishes how one application can communicate with another. It's like a contract between the two parts that says "If you send A, I'll always respond B. If you send C, I'll always respond D..." and so on.

Having this set of rules, the client knows exactly what it has to require in order to complete a certain task, and the server knows exactly what the client will require when a certain action has to be performed.

APIs are absolutely everywhere in current software development. Almost any kind of application will use a client-server model enabled by API communication. That's why I think it's a very good idea for us as developers to get to know them well.

The most popular ways to implement APIs nowadays are REST and GraphQl. We'll also take a look at SOAP, which was quite popular some years ago and is still used in some niche sectors.

If you'd like a deeper intro to what APIs are, here's an awesome video about it.

With all this in mind, let's get into the details of how SOAP, REST and GraphQL APIs work.

How SOAP APIs Work

Simple Object Access Protocol (SOAP) is a messaging protocol used for exchanging structured data between different systems over the internet. SOAP is an XML-based protocol and is considered one of the earliest web service protocols.

SOAP was first introduced in 1998 by Microsoft as a successor to Common Object Request Broker Architecture (CORBA) and Distributed Component Object Model (DCOM).

SOAP was designed to provide a platform-independent way to exchange data between different systems over the internet. SOAP was later standardized by the World Wide Web Consortium (W3C) in 2003.

Main Characteristics:

Protocol-Independent: SOAP is designed to work with any protocol that supports the transmission of messages over the internet, including HTTP, SMTP, and FTP.
Platform-Independent: SOAP is designed to work with any programming language or platform that supports XML and can send and receive HTTP messages.
Messaging: SOAP is a messaging protocol and defines a set of rules for exchanging structured data between different systems.
Security: SOAP supports several security standards, including encryption, digital signatures, and authentication.
Extensibility: SOAP allows for the creation of custom extensions to the protocol to support specific requirements.

Pros:

Standardization: SOAP is a well-established and standardized protocol, making it a reliable choice for exchanging data between different systems.
Security: SOAP provides built-in support for several security standards, making it a secure choice for transmitting sensitive data.
Extensibility: SOAP is highly extensible and allows for the creation of custom extensions to support specific requirements.

Cons:

Complexity: SOAP can be complex to implement and may require specialized expertise.
Overhead: SOAP messages can be large and can require significant processing resources, resulting in increased overhead.
Performance: SOAP can be slower compared to other API protocols due to its messaging nature.

Best for:

When you need to transmit sensitive data: SOAP supports several security standards, making it a secure choice for transmitting sensitive data.
When you need to support complex data structures: SOAP supports complex data structures, making it a good choice for transmitting and exchanging data between different systems.
When you need a reliable and standardized protocol: SOAP is a well-established and standardized protocol, making it a reliable choice for exchanging data between different systems.

SOAP APIs were widely used in the early days of web services and are still used in several industries and sectors today, although REST and GraphQL have become more popular in recent years.

Here are some industries, sectors, and types of applications in which SOAP is still the main option:

Healthcare: SOAP is still widely used in healthcare applications, especially in electronic health records (EHR) and health information exchanges (HIE). This is because SOAP provides a secure and reliable way to transmit sensitive patient information between different systems.
Finance: SOAP is still used in financial applications, such as payment gateways and trading platforms, because it provides a secure and reliable way to transmit financial data.
Enterprise applications: SOAP is still used in enterprise applications, such as customer relationship management (CRM) and enterprise resource planning (ERP) systems, because it provides a standardized and reliable way to exchange data between different systems.
Legacy systems: Many older systems and applications still use SOAP APIs, and it can be costly and time-consuming to migrate them to newer technologies.

In conclusion, SOAP APIs have been around for a long time and are still used in several industries to exchange data between different systems.

SOAP might be the most beneficial option for developing an API when you need to transmit sensitive data, support complex data structures, or need a reliable and standardized protocol.

About XML

As mentioned, SOAP APIs use XML as the main format for data transmission, so let's explain how XML works.

XML stands for Extensible Markup Language. It is a markup language that allows users to create custom tags and attributes to describe the structure and content of data.

XML uses a set of rules for encoding documents in a format that is both human-readable and machine-readable. This is achieved by using tags to define elements of a document, similar to HTML.

For example, an XML document may have a tag called to define an element representing a person, with nested tags for properties such as , , and

. XML also allows users to define custom tags to describe their data in a way that is specific to their needs.

XML is widely used in various industries, including finance, healthcare, and government. It is often used for data exchange between different applications and systems, as it provides a standardized way of representing data that can be easily parsed by computers. XML is also used for storing configuration files and metadata for various applications.

Overall, XML provides a flexible and extensible way of describing and exchanging data that can be easily processed by computers. However, its use has declined in recent years with the rise of more modern formats such as JSON and YAML, which are more lightweight and easier to use for many applications.

How to Consume a SOAP API

Here's an example of how you can make a simple request to a SOAP API from a JavaScript front-end application:

// specify the URL of the SOAP API endpoint
const url = 'http://www.example.com/soap-api';

// specify the SOAP message to send
const soapMessage = '' +
                    '' +
                    '' +
                    '' +
                    '' +
                    '123' +
                    '' +
                    '' +
                    '';

// set the content type of the SOAP message
const contentType = 'text/xml';

// make the fetch request
fetch(url, {
  method: 'POST', // SOAP uses the HTTP POST method to send requests to a server.
  headers: {
    'Content-Type': contentType,
    'SOAPAction': 'http://example.com/GetData'
  },
  body: soapMessage
})
  .then(response => response.text())
  .then(xml => {
    // handle the XML response
    const parser = new DOMParser();
    const xmlDoc = parser.parseFromString(xml, 'text/xml');
    const value = xmlDoc.getElementsByTagName('Value')[0].childNodes[0].nodeValue;
    console.log(value);
  })
  .catch(error => console.error(error));

Let's break down what each line does:

const url = 'http://www.example.com/soap-api'; specifies the URL of the SOAP API endpoint.
const soapMessage = '' + ... specifies the SOAP message to send to the API endpoint. This is a string that contains the XML markup for the SOAP message.
const contentType = 'text/xml'; specifies the content type of the SOAP message.
fetch(url, { ... }) makes a fetch request to the API endpoint using the specified URL and options.
method: 'POST', specifies the HTTP method to use for the request.
headers: { ... } specifies the headers to include in the request.
'Content-Type': contentType, sets the content type of the request header to the value of contentType.
'SOAPAction': 'http://example.com/GetData' sets the SOAPAction header to the value of the SOAP action that corresponds to the API method being called.
body: soapMessage sets the body of the request to the value of soapMessage.
.then(response => response.text()) converts the response to text format.
.then(xml => { ... }) handles the response from the server.

A typical response might look like this:


<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
      <ns1:GetDataResponse xmlns:ns1="http://example.com">
         <ns1:Result>
            <ns1:Id>123ns1:Id>
            <ns1:Value>42ns1:Value>
         ns1:Result>
      ns1:GetDataResponse>
   SOAP-ENV:Body>
SOAP-ENV:Envelope>

To access the values in the XML response, you can use the DOMParser API to parse the response into an XML document object, and then use DOM traversal methods to navigate the document and extract the values.

For example, the following code extracts the value of the Value element from the XML document object:

const parser = new DOMParser();
const xmlDoc = parser.parseFromString(xml, 'text/xml');
const value = xmlDoc.getElementsByTagName('Value')[0].childNodes[0].nodeValue;
console.log(value); // output: 42

Here's what each line does:

const parser = new DOMParser(); creates a new instance of the DOMParser object, which is used to parse the XML response.
const xmlDoc = parser.parseFromString(xml, 'text/xml'); parses the XML response into an XML document object.
const value = xmlDoc.getElementsByTagName('Value')[0].childNodes[0].nodeValue; retrieves the value of the Value element from the XML document object. This line uses the getElementsByTagName() method to get all elements with the tag name Value, and then accesses the first element (assuming there's only one), and gets the value of its first child node. The value is then assigned to the value variable.
console.log(value); // output: 42 logs the value of the Value element to the console.

Overall, SOAP responses tend to be more verbose and complex than responses from REST or GraphQL APIs, due to their use of XML and the envelope format. But this format provides a standardized way of exchanging information that can be useful in certain industries and use cases.

How REST APIs Work

Representational State Transfer (REST) is a widely used architectural style for building web services and APIs.

REST was first introduced in 2000 by Roy Fielding in his doctoral dissertation, "Architectural Styles and the Design of Network-based Software Architectures." Fielding, who was also one of the primary authors of the HTTP protocol, defined REST as an architectural style that is based on the principles of the web.

RESTful APIs are designed to be simple, scalable, and flexible. They are often used in web and mobile applications, as well as in Internet of Things (IoT) and microservices architectures.

Main Characteristics:

Stateless: REST APIs are stateless, which means that each request contains all the necessary information to process it. This makes it easier to scale the API and improves performance by reducing the need to store and manage session data on the server.
Resource-based: REST APIs are resource-based, which means that each resource is identified by a unique URI (Uniform Resource Identifier) and can be accessed using standard HTTP methods such as GET, POST, PUT, and DELETE.
Uniform Interface: REST APIs have a uniform interface that allows clients to interact with resources using a standardized set of methods and response formats. This makes it easier for developers to build and maintain APIs, and for clients to consume them.
Cacheable: REST APIs are cacheable, which means that responses can be cached to improve performance and reduce network traffic.
Layered System: REST APIs are designed to be layered, which means that intermediaries such as proxies and gateways can be added between the client and server without affecting the overall system.

Pros:

Easy to learn and use: REST APIs are relatively simple and easy to learn compared to other APIs.
Scalability: The stateless nature of REST APIs makes them highly scalable and efficient.
Flexibility: REST APIs are flexible and can be used to build a wide range of applications and systems.
Wide support: REST APIs are widely supported by development tools and frameworks, making it easy to integrate them into existing systems.

Cons:

Lack of standards: The lack of strict standards for REST APIs can lead to inconsistencies and interoperability issues.
Limited functionality: REST APIs are designed to handle simple requests and responses and may not be suitable for more complex use cases.
Security concerns: REST APIs can be vulnerable to security attacks such as cross-site scripting (XSS) and cross-site request forgery (CSRF) if not implemented properly.

Best for:

REST APIs are well-suited for building web and mobile applications, as well as microservices architectures and IoT systems.
They are particularly useful in situations where scalability and flexibility are important, and where developers need to integrate with existing systems and technologies.

In summary, REST APIs are a popular and widely used architectural style for building web services and APIs. They are simple, scalable, and flexible, and can be used to build a wide range of applications and systems.

While there are some limitations and concerns with REST APIs, they remain a popular and effective option for building APIs in many different industries and sectors.

How to Consume a REST API

Here's an example of how to make a simple GET request to a REST API from a JavaScript front-end application, and how to access the values within the response:

fetch('https://jsonplaceholder.typicode.com/todos/1')
  .then(response => response.json())
  .then(data => {
    console.log(data);
    // Access the values within the response here
  })
  .catch(error => console.error(error));

Here's what each line does:

fetch('https://jsonplaceholder.typicode.com/todos/1') initiates a GET request to the specified URL.
.then(response => response.json()) converts the response from JSON format to a JavaScript object.
.then(data => { ... }) defines a function that will be executed when the response has been successfully converted to a JavaScript object. This function will have access to the JavaScript object containing the response data.
console.log(data); logs the response data to the console. You can inspect the response data to determine how to access the values within the response.

To access the values within the response, you can use standard JavaScript object traversal techniques, such as dot notation or bracket notation. For example, if the response from the REST API is in the following format:

{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

You can access the title value using dot or bracket notation like this:

console.log(data.title); // output: "delectus aut autem"
console.log(data['title']); // output: "delectus aut autem"

Here, data refers to the JavaScript object that contains the response data.

REST API responses are generally simpler and more lightweight than SOAP responses, and they are often formatted in either JSON or XML. The use of standard formats makes it easier for clients to parse the response and extract the relevant data.

Additionally, REST APIs often use standard HTTP status codes to indicate the success or failure of a request, which can simplify error handling on the client side.

Overall, REST APIs are a popular and widely used approach to building web APIs due to their simplicity, flexibility, and ease of use.

How GraphQL APIs Work

GraphQL is a query language and runtime for APIs that was developed by Facebook in 2012. It was released to the public in 2015 and has since gained popularity as an alternative to REST APIs.

Main Characteristics:

Strongly Typed: GraphQL APIs are strongly typed, which means that each field has a specific data type. This makes it easier to validate and handle data on the client and server sides.
Query Language: GraphQL has its own query language that allows clients to specify exactly what data they need. This reduces over-fetching of data and improves performance.
Single Endpoint: GraphQL APIs have a single endpoint, which means that clients can fetch all the data they need from a single request.
Declarative: GraphQL APIs are declarative, which means that clients specify what they want, not how to get it. This allows for more efficient and flexible data fetching.
Schema-Driven: GraphQL APIs are schema-driven, which means that the schema defines the structure of the data and the available queries and mutations. This makes it easier for developers to understand and work with the API.

Pros:

Efficient Data Fetching: GraphQL APIs allow clients to fetch only the data they need, reducing over-fetching and improving performance.
Strongly Typed: GraphQL APIs are strongly typed, making it easier to validate and handle data.
Single Endpoint: GraphQL APIs have a single endpoint, reducing the complexity of the API and making it easier to work with.
Schema-Driven: GraphQL APIs are schema-driven, which makes it easier for developers to understand and work with the API.

Cons:

Complexity: GraphQL APIs can be more complex to set up and work with compared to REST APIs.
Caching: Caching can be more challenging with GraphQL APIs due to the flexible nature of the API.
Learning Curve: GraphQL requires a learning curve for both developers and clients, as it has its own query language and approach to data fetching.

Best for:

Efficient and flexible needs: GraphQL is well-suited for building applications that require efficient and flexible data fetching, such as mobile and web applications.
Complex data requirements: It is particularly useful in situations where there are complex data requirements and where over-fetching data can cause performance issues.

In conclusion, GraphQL is a query language and runtime for APIs that provides efficient and flexible data fetching capabilities.

How to Consume a GraphQL API

Here's an example of how to make a simple request to retrieve information from a GraphQL API from a JavaScript front-end application, and how to access the values within the response:

fetch('https://api.example.com/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: `
      query {
        user(id: 123) {
          name
          email
          posts {
            title
          }
        }
      }
    `
  })
})
.then(response => response.json())
.then(data => {
  console.log(data);
  // Access the values within the response here
})
.catch(error => console.error(error));

Here's what each line does:

fetch('https://api.example.com/graphql', { ... }) initiates a POST request to the specified GraphQL API endpoint. The second argument to the fetch() function is an options object that specifies the HTTP method, headers, and request body.
method: 'POST' specifies that the HTTP method for the request is POST.
headers: { 'Content-Type': 'application/json' } specifies the Content-Type header for the request, which is application/json to indicate that the request body is in JSON format.
body: JSON.stringify({ ... }) specifies the request body as a JSON-encoded string. In this example, the request body is a GraphQL query that retrieves information about a user with the ID 123.
.then(response => response.json()) converts the response from JSON format to a JavaScript object.
.then(data => { ... }) defines a function that will be executed when the response has been successfully converted to a JavaScript object. This function will have access to the JavaScript object containing the response data.
console.log(data); logs the response data to the console. You can inspect the response data to determine how to access the values within the response.

{
  "data": {
    "user": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "posts": [
        { "title": "Post 1" },
        { "title": "Post 2" }
      ]
    }
  }
}

You can access the name value using dot or bracket notation like this:

console.log(data.data.user.name); // output: "John Doe"
console.log(data['data']['user']['name']); // output: "John Doe"

Here, data refers to the JavaScript object that contains the response data. The response data is wrapped in a data object, and the values can be accessed by traversing the object using dot notation or bracket notation.

GraphQL API responses are typically more focused and specific than REST API responses because the client can specify exactly what data they want to receive. This makes it easier to avoid overfetching or underfetching data, and can improve performance by reducing the amount of data transferred over the network.

Additionally, GraphQL APIs can provide a more flexible schema that can be easily modified over time without breaking existing clients. Overall, GraphQL APIs are a popular choice for building modern web applications due to their flexibility, efficiency, and ease of use.

Wrapping Up

Well everyone, as always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

How to Use TypeScript with GraphQL using TypeGraphQL

freeCodeCamp — Wed, 13 Apr 2022 00:18:19 +0000

By Dillion Megida

In this tutorial, I'll explain what TypeScript and GraphQL are, and the benefits of using them.

Then I'll show you how you can use them together using TypeGrapQL, and why you'd want to do this.

What is TypeScript?

TypeScript is a superset of JavaScript that compiles to JavaScript for production. It's like JavaScript, but with powers – type powers.

TypeScript helps you build typed applications that help you avoid static type errors in those apps and make predictable code.

Without TypeScript, a function declared to receive a string typed argument may receive a number typed argument during execution, and you may get a runtime error. This can be bad for production code.

With TypeScript, such a function will result in a compile-time error unless the appropriate type is passed.

TypeScript can handle more than primitive types. It can also ensure that correct, expected, structured objects are typed. This means a missing object property can also result in an error.

TypeScript helps us build more predictable JavaScript code during development through type-checking. It is also integrated into editors like VSCode, which makes it easier to spot type errors while writing code.

TypeScript takes an extra step to compile to JavaScript for use. While some libraries like React do this internally for you, you may have to set it up yourself if you're building without such tools. But I'd say it is worth it.

What is GraphQL?

GraphQL is another method for managing APIs. It's an alternative to Rest APIs that allows you to request "only the data you need". This helps reduce the amount of data that needs to be sent to the client from the server.

For example, with a Rest API, an endpoint may return all users' data when only their email and phone number are needed at that point. This is termed "over-fetching". With GraphQL, the client can request such specific data.

GraphQL also comes with type definitions, which exist in schema objects. GraphQL uses Schema objects to know what properties are query-able, and basically, the type of queries that are accepted. It also throws an error when an unaccepted query is executed.

However, these type definitions to limited to schema objects. They do not give you overall static typing in your application. And that's why TypeScript is an excellent addition, as we'll see in the rest of this article.

Advantages of Using TypeScript and GraphQL

Using TypeScript and GraphQL ensures that static typing exists all through your application.

Without TypeScript, you can still create query types with GraphQL. But there's a limitation to this.

GraphQL types only exist in the GraphQL schema. The buildSchema function from the GraphQL library is used to create the schema object:

const schema = buildSchema(`
    type Query {
        name(firstname: String!, lastname: String!): String
    }
`)

We've created the schema object, and now we need a resolver:

const root = {
    name: variables => {
        return `My name is ${firstname} ${lastname}!`
    },
}

On executing the query with wrongly typed variables in a GraphQL playground, we would get errors:

GraphQL playground showing error for wrong type provided to query

But the resolvers are not aware of the type definition in the schema object. As you can see, the resolver is a regular JavaScript function. This means, we don't get static typing in the resolver.

Say, for example, we provide the wrong argument types to the resolver, or we return a different type from the resolver that the schema did not expect. We may introduce bugs to our code without knowing it.

And this is why TypeScript is beneficial. With TypeScript, we have type definitions in the schema object and in the resolvers, thereby synchronizing both of them and making our code much more predictable.

How to Use TypeScript and GraphQL

In this section, we'll be using TypeScript and GraphQL to create a simple GraphQL API on an Express server.

Step 1: Create a project folder

You can name it whatever you want, but we'll be using the graphql-ts-example folder for this tutorial:

mkdir graphql-ts-example
cd graphql-ts-example
npm init -y

Step 2: Install dependencies

We'll use the following dependencies for this tutorial:

graphql: the JavaScript library for GraphQL
express: a web framework for Node that allows us to create APIs and a backend server
express-graphql: for creating a GraphQL server for the APIs
ts-node: for executing TypeScript code in Node
typescript: for compiling TypeScript code to JavaScript
@types/express: for using Express in TypeScript
nodemon: for restarting the server when changes are made

In your terminal, run:

npm install graphql express express-graphql
npm install -D nodemon ts-node @types/express typescript

For testing our API, we'll be using the GraphQL playground provided by express-graphql.

Step 3: Setting up our scripts

In package.json, update the scripts object to this:

"scripts": {
    "start": "nodemon --exec ts-node src/index.ts",
}

Also, add a configuration file for TypeScript, tsconfig.json:

{
    "compilerOptions": {
        "target": "es2018",
        "module": "commonjs",
        "jsx": "preserve",
        "strict": true,
        "esModuleInterop": true,
        "lib": ["es2018", "esnext.asynciterable"]
    },
    "exclude": ["node_modules"]
}

With this, we can run our server with npm start.

Step 4: Write the code

We'll create an Express server with a GraphQL API that allows us to fetch users, create a user, and update a user's data.

Create a new directory called "src" and add the index.ts file into it. We have our imports in the file as follows:

import { buildSchema } from "graphql"
import express from "express"
import { graphqlHTTP } from "express-graphql"

Then we need our users list. Ideally, this would come from a database, but we'll hardcode it here:

const users = [
    { id: 1, name: "John Doe", email: "johndoe@gmail.com" },
    { id: 2, name: "Jane Doe", email: "janedoe@gmail.com" },
    { id: 3, name: "Mike Doe", email: "mikedoe@gmail.com" },
]

Next, we build the GraphQL schema:

const schema = buildSchema(`
    input UserInput {
        email: String!
        name: String!

    }

    type User {
        id: Int!
        name: String!
        email: String!
    }

    type Mutation {
        createUser(input: UserInput): User
        updateUser(id: Int!, input: UserInput): User
    }

    type Query {
        getUser(id: String): User
        getUsers: [User]
    }
`)

From our schema, we've defined:

a user input with two required properties, which is required when creating a user
a user type with three required properties
a GraphQL mutation where we create users and update users
and a GraphQL query for getting a particular user or all users.

Now, we need to define our TypeScript types for static typing:


type User = {
    id: number
    name: string
    email: string
}

type UserInput = Pick"email" | "name">

Next, our resolvers:

const getUser = (args: { id: number }): User | undefined =>
    users.find(u => u.id === args.id)

const getUsers = (): User[] => users

const createUser = (args: { input: UserInput }): User => {
    const user = {
        id: users.length + 1,
        ...args.input,
    }
    users.push(user)

    return user
}

const updateUser = (args: { user: User }): User => {
    const index = users.findIndex(u => u.id === args.user.id)
    const targetUser = users[index]

    if (targetUser) users[index] = args.user

    return targetUser
}

const root = {
    getUser,
    getUsers,
    createUser,
    updateUser,
}

And finally, our Express route and server:

const app = express()

app.use(
    "/graphql",
    graphqlHTTP({
        schema: schema,
        rootValue: root,
        graphiql: true,
    })
)

const PORT = 8000

app.listen(PORT)

console.log(`Running a GraphQL API server at http://localhost:${PORT}/graphql`)

With what we have above, our resolvers are typed following the schema definition. This way, our resolvers are in sync. On localhost:4000/graphql, we can see the GraphQL playground:

GraphQL playground showing working queries

Although we can see how beneficial TypeScript is, we also cannot deny the hassle of writing type definitions after creating a schema object.

This codebase is small, so that can be easier, but imagine something big, with many resolvers and having to create type definitions for each one 😩

We need a better way of doing this. We need something that allows us to create type definitions in one place, as the main source of truth, and then use them in our resolvers and schema objects.

How to Use TypeGraphQL to Improve Your Typed GraphQL

The goal of TypeGraphQL is to make it seamless to enjoy static typing in your resolvers and create your schemas from one place.

It comes with its syntax, which is another learning process. But it's not so steep – it's a step in the right direction.

Let's improve our codebase by using TypeGraphQL.

We'd need a couple of dependencies:

class-validator: allows the use of decorators for validation
type-graphql: the TypeGraphQL library itself, that allows you to create schemas and resolvers with TypeSCript, using classes and decorators
reflect-metadata: for runtime reflection of types (learn more about this here: Metadata reflection in TypeScript)

In your terminal, run:

npm install class-validator type-graphql reflect-metadata

In your tsconfig.json, add the following to the compilerOptions object:

"compilerOptions": {
    // ...
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
}

These are important so that TypeScript doesn't complain about the use of decorators. They are still in experimental mode.

Now, let's update our codebase using TypeGraphQL. Create a new directory called "users". In it, we'll have the schema and resolvers.

Create a new file in "users" called "users.schema.ts":

// users.schema.ts

import { Field, ObjectType, InputType } from "type-graphql"

@ObjectType()
export class User {
    @Field()
    id!: number
    @Field()
    name!: string
    @Field()
    email!: string
}

@InputType()
export class UserInput implements Pick"name" | "email"> {
    @Field()
    name!: string
    @Field()
    email!: string
}

First, we have the User class, which is decorated with the ObjectType decorator. This tells GraphQL that this class is a GraphQL type. In GraphQL, this is interpreted as:

buildSchema(`
    type User {
        id: Int!
        name: String!
        email: String!
    }

    input UserInput {
        name: String!
        email: String!
    }
`)

Next, our resolvers. Create a users.resolvers.ts file in the "users" directory:


// users.resolvers.ts

import { Query, Resolver, Mutation, Arg } from "type-graphql"
import { UserInput, User } from "./users.schema"

@Resolver(() => User)
export class UsersResolver {
    private users: User[] = [
        { id: 1, name: "John Doe", email: "johndoe@gmail.com" },
        { id: 2, name: "Jane Doe", email: "janedoe@gmail.com" },
        { id: 3, name: "Mike Doe", email: "mikedoe@gmail.com" },
    ]

    @Query(() => [User])
    async getUsers(): Promise {
        return this.users
    }

    @Query(() => User)
    async getUser(@Arg("id") id: number): Promiseundefined> {
        const user = this.users.find(u => u.id === id)
        return user
    }

    @Mutation(() => User)
    async createUser(@Arg("input") input: UserInput): Promise {
        const user = {
            id: this.users.length + 1,
            ...input,
        }

        this.users.push(user)
        return user
    }

    @Mutation(() => User)
    async updateUser(
        @Arg("id") id: number,
        @Arg("input") input: UserInput
    ): Promise {
        const user = this.users.find(u => u.id === id)

        if (!user) {
            throw new Error("User not found")
        }

        const updatedUser = {
            ...user,
            ...input,
        }

        this.users = this.users.map(u => (u.id === id ? updatedUser : u))

        return updatedUser
    }
}

There are a few decorators to take note of here:

there's the Resolver decorator, which decorates the class as an object with many query and mutation resolve methods. The beauty here is we're defining the queries and mutations and the resolve methods in the same class.
there's the Query decorator, which tells GraphQL that this is a query and the respective resolve method
there's the Mutation decorator, which tells GraphQL that this is a mutation and the respective resolve method
there's the Arg decorator, which tells GraphQL that this argument is a GraphQL argument for the resolver.

As you'll notice, without creating a type definition for the User object, we could simply use the class exported from the schema file.

The above code will be interpreted to GraphQL as:

buildSchema(`
    type Query {
        getUsers: [User]
        getUser(id: Int!): User
    }

    type Mutation {
        createUser(input: UserInput): User
        updateUser(id: Int!, input: UserInput): User
    }
`)

// resolvers

Back in src/index.ts, here's what the code looks like:

import "reflect-metadata"
import { buildSchema } from "type-graphql"
import express from "express"
import { graphqlHTTP } from "express-graphql"

import { UsersResolver } from "./users/users.resolver"

async function main() {
    const schema = await buildSchema({
        resolvers: [UsersResolver],
        emitSchemaFile: true,
    })

    const app = express()

    app.use(
        "/graphql",
        graphqlHTTP({
            schema: schema,
            graphiql: true,
        })
    )

    app.listen(8000)

    console.log("Running a GraphQL API server at http://localhost:8000/graphql")
}

main()

The buildSchema function comes from the type-graphql library this time around. Back in the GraphQL playground, our queries work as expected:

GraphQL playground showing GraphQL mutation for creating user

Here's the GitHub repository for this project: graphql-typescript-example

Conclusion

In this article, we've learnt what GraphQL and TypeScript are, and seen the limitations of using GraphQL without TypeScript.

We've also seen a beautiful way to use GraphQL and TypeScript together – TypeGraphQL.

If you found this helpful, kindly share it with others : )

GraphQL vs REST API – Which Should You Use for Back End API Development?

freeCodeCamp — Mon, 25 Oct 2021 15:02:30 +0000

By Aagam Vadecha

REST and GraphQL are both standard ways to develop backend APIs. But over the past decade REST APIs have dominated as a choice for developing backend API's. And many companies and developers use it actively in their projects.

But REST has some limitations, and there's another alternative available – GraphQL. GraphQL is a great choice for developing APIs in large codebases.

What is GraphQL?

GraphQL was developed by Facebook in 2012 for internal usage and made public in 2015. It is a query language for APIs and a runtime for fulfilling those queries with your existing data. Many companies use it in production.

The official website introduces GraphQL like this:

GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

And we'll see how all this works in this blog.

Issues With REST APIs

Querying Multiple Endpoints
OverFetching
UnderFetching and n+1 Request Problem
Not super fast to cope up with changing client end requirements
High Coupling between Backend Controllers and Frontend Views

So, what are these issues and how does GraphQL solve them? Well, we'll learn more going forward. But first we'll need to make sure you're comfortable with the basic concepts of GraphQL like the type system, schema, queries, mutations, and so on.

Now we'll look at some examples to better understand the disadvantages of using REST APIs.

Overfetching

Let's assume that we need to show this User Card in the UI.

With REST, the request is going to be a GET at /users/1.

The problem here is that the server returns a fixed data-structure, something like this:

{
    "_id": "1",
    "name": "Aagam Vadecha",
    "username": "aagam",
    "email": "testemail@gmail.com",
    "currentJobTitle": "Software Engineer",
    "phone": "9876543210",
    "intro": "As a software engineer my daily routine revolves around writing cleancode, maintaining infrastructure, and building scalable softwaresystems. In my free time I love to write tech blogs, freelance, listenmusic, and watch thrillers.",
    "website": "https://www.aagam.tech",
    "gender": "MALE",
    "city": "Surat",
    "state": "Gujarat",
    "country": "India",
    "display_picture": "8ba58af0-1212-4938-8b4a-t3m9c4371952",
    "phone_verified": true,
    "email_verified": true,
    "_created_at": "2021-03-08T14:13:41Z",
    "_updated_at": "2021-03-08T14:13:41Z",
    "_deleted": false
}

The server returns extra data (aside from the Name, Intro, and Job Designation) which is not required at the client-end to build the card at this point – but the response still has it. This is called overfetching.

Overfetching brings extra data in each request which is not required by the client. And this increases the payload size and eventually that has an effect on the overall response time of the query.

What's worse, the situation escalates when a query is bringing data from multiple tables even though the client doesn't require it right then. So if we can avoid it, we definitely should

With GraphQL, the query inside the request body would look something like this:

It will only return the name, intro, and currentJobTitle as required by the client, so the overfetching problem is solved.

Underfetching and the n+1 request problem

Now let's assume this UserList needs to be shown in the UI.

With REST, considering "experience" is a table which has a foreign key of user_id, there are three possible options

One is to send some exact fixed data-structure from all foreign-key linked tables to the users table in the GET /users request, and many frameworks provide this option.

{
    "_id": "1",
    "name": "Aagam Vadecha",
    "username": "aagam",
    "email": "testemail@gmail.com",
    "currentJobTitle": "Software Engineer",
    "phone": "9876543210",
    "intro": "As a software engineer my daily routine revolves around writing cleancode, maintaining infrastructure, and building scalable softwaresystems. In my free time I love to write tech blogs, freelance, listenmusic, and watch thrillers.",
    "website": "https://www.aagam.tech",
    "gender": "MALE",
    "city": "Surat",
    "state": "Gujarat",
    "country": "India",
    "display_picture": "8ba58af0-1212-4938-8b4a-t3m9c4371952",
    "phone_verified": true,
    "email_verified": true,
    "_created_at": "2021-03-08T14:13:41Z",
    "_updated_at": "2021-03-08T14:13:41Z",
    "_deleted": false,
    "experience": [
        {
            "organizationName": "Bharat Tech Labs",
            "jobTitle": "Software Engineer",
            "totalDuration": "1 Year"
        }
    ],
    "address": [
        {
            "street": "Kulas Light",
            "suite": "Apt. 556",
            "city": "Gwenborough",
            "zipcode": "929983874",
            "geo": {
                "lat": "-37,3159",
                "lng": "81.1496"
            }
        }
    ]
}

But this method makes expensive queries, overfetches all other /users requests as well, and ends up bringing back a lot of data from all foreign tables (address, experience) which is not required in most cases.

For example, you want user data somewhere else in the frontend where you just need to show user's website so you make a GET user/1 request. But it overfetches data from the experience table as well as the address table, which you don't need at all.

The second option is that the client can make multiple trips to the server like this:

GET /users 
GET users/1/experience

This is an example of underfetching, as one endpoint doesn't have enough data. But multiple network calls slows down the process and affects the user experience. :(

Also, in this specific case of a List, underfetching escalates and we run into the n+1 request problem.

You need to make an API call to get all users and then individual API calls for each user to get their experience, something like this:

 GET /users 
 GET /users/1/experience 
 GET /users/2/experience 
 ...
 GET /users/n/experience.

This is known as the n+1 request problem. To solve this issue, what we generally do is the third option, which we'll discuss now.

Another option is to make a custom controller on the server which returns the data-structure that meets the client requirements at that point in time.
```
GET /user-experience
```
This is what is done in major real world REST API cases.

On the other hand, a simple GraphQL request which would seamlessly work without any development required on the server end, would look something like this:

No overfetching, no underfetching, and no development on the server. Simply fantastic!

Tight coupling between front end views and back end APIs

Okay, so you might argue that you can just use REST, make the server controller with a one time initial development effort, and be happy – right?

But there's a major drawback which comes along with using custom controllers.

We have formed a tight coupling with the front-end view and the back-end controller, so overall it needs more effort to cope with changes on the client end. It also gives us less flexibility.

As Software Engineers, we know how often requirements change. The custom controller at this point GET /user-experience is returning data depending on what the front-end view wants to display (user-name and current-role). So when a requirement changes, we need to refactor both the client and server.

For example, after a considerable amount of time, requirements change and instead of the experience data the UI needs to show a user's last transaction info.

With Rest, we would need to make the relevant changes in the front end layer. Additionally, in order to return transaction data instead of experience data from the back end, the custom controller will either need to be refactored (data sent, route, etc) or we'll need to make a new controller in case we want to preserve the old one.

So basically, a change in client requirements greatly influences what is to be returned by the server – which means we have tight coupling between the front end and the back end!

It would be better not to have to make any changes on the server but only the front end.

With GraphQL we won't need to make any changes in the server side. The change in the front end query would be as minimal as this:

No server API refactoring, deployment, testing – this means time and effort saved!

Conclusion

As I hope you can see from this article, GraphQL has a number of advantages over REST in many areas.

It might take more time to set up GraphQL initially, but there are many scaffolders which make that job easier. And even if it takes more time in the beginning, it gives you long term advantages and is totally worth it.

Thanks for reading!
I hope you liked this article, and that it gave you more insights to help you make your next choice. If you need some help, feel free to reach out to me on LinkedIn.

GraphQL for Front End Developers

freeCodeCamp — Tue, 19 Oct 2021 17:19:00 +0000

By Gaurav Tewari

If you are a front end developer who is new to the world of GraphQL and you're thinking about getting started with it, this article is for you.

In this article, we will explore GraphQL basics and kick start our journey with it by building a simple project.

What is GraphQL?

GraphQL is a query language that lets apps fetch data from the API's. But what it does differently is that is allows clients to specify how to structure the data when it is returned by the server. This means that the client only asks for the data it needs and even specifies the format in which it needs the data.

But what problem does it actually solve?

It solves the problem of under fetching and over fetching. Ok but what's that? Well, let me tell you.

Let's say you only need to display a userName, userImage, and Name in your profile page on your website or app. But when you request the data you are getting lots of other information about the user which you don't need.

This is called over fetching – you are fetching a lot of data, even the data you don't need. On the other hand, under fetching is when we get less data than you need. So neither one is great.

under Fetching example

You might think ok, that's not a problem at all. Well, it's not a big problem in small scale applications. But what about in large scale applications that have millions of users? In those cases, over fetching and under fetching waste a lot of resources, which is where GraphQL comes in.

How to Get Started With GraphQL

Here we'll cover some key concepts you need to know before getting started with graphQL

GraphQL PlayGround

GraphQL playground is an interactive, Graphical IDE for GraphQL where you can visually explore the server. In it you can test various GraphQL queries and see their results in front of your eyes.

Here is a link to GraphQL playground you can check out.

GraphQL playground

If you click on the play button it will run the query.

How do you request, write, or post data in GraphQL?

You request data through a query in GraphQL. And to write or post data, you use mutations.

Whenever we perform a GraphQL operation, we specify whether it is a mutation or a query. Then we name that operation, and this is the basic way of performing a GraphQL query.


GraphQLOperatoinType Name {
 ....
 ........
 .....
 ...
}

To make a simple query, the syntax would be:

query getData {
...
}

Similarly, to add a mutation we would write mutation in place of query.

Now since we know the basics, let's get our hands dirty. We will be using the Anilist API to get a list of anime shows.

Apollo studio

How to Use Apollo Studio

You've gotten a small taste of GraphQL playground, but there's something even more awesome called Apollo Studio. It makes life easier as a front end developer. In it, you just need select the fields you want and it writes a query for you.

From the left hand side select the fields you want in your Query, and that's it. GraphQL will automatically create a query for you. Now you've made the query, but how do you use it in your application?

Well let's get started building a simple Anime App with it.

We'll use React in this project, but you can choose any framework or library you'd like.

Firstly, create a new project in React:

npx create-react-app graphql-example

Now once the project is created go inside the project directory and install the Apollo client.

npm install graphql @apollo/client

Once it's done, go the src/index.js and import ApolloClient, InMemoryCache, and ApolloProvider:

import {ApolloClient, InMemoryCache, ApolloProvider} from '@apollo/client';

Apollo Client is a class which represents the Apollo client itself, and we use it to create a new client instance.

Here we need to provide a couple of things to it. One is the URI where we specify the URL of our GraphQL server. Also every instance of our Apollo client needs a cache so it can reduce the network requests and can make our app much faster.

This is what our new client look like:

const client = new ApolloClient({
  uri : 'https://graphql.anilist.co/',
  cache: new InMemoryCache(),
})

Now we need to make this client available throughout our component tree so we wrap our app's top level component in ApolloProvider.

Now we are done with the initial setup, so it's time to make a query and ask our API for the data – but how do we do that?

We can do so using the useQuery hook. But before that we need to define a query, which we can do using the GQL (we need to wrap our query inside it). So now, import these two from the Apollo client:

import {useQuery, gql} from '@apollo/client';

After importing them, we'll wrap our query inside GQL:

 const AnimeList = gql`
 query Query {
  Page {
    media {
      siteUrl
      title {
        english
        native
      }
      description
      coverImage {
        medium
      }
      bannerImage
      volumes
      episodes
    }
  }
}
}



`;

At this point you must be wondering if the query part is done, how do we get data from it now?

That's where the useQuery hook comes handy. It returns loading, error, and data properties we can use.

  const {loading, error, data} = useQuery(AnimeList);

For now we can just display the data to check whether our app works or not:

if(loading) return(<> Loading);
  if(error) return(<>{JSON.stringify(error)})
  return (
   <>
   {JSON.stringify(data)}
   );

Well it works for now – time to style it.

Maybe we can use object chaining to implement that nicely:

 "container"> 
     <h1> 🐈 Anime List h1>
     <hr width="80%" />
   {data?.Page?.media.map(anime => (
     <>
   <div className="card" >
      <img    src={anime.coverImage.medium}/>
      <div> 
         <h1>{anime.title.english} h1>
           <div className="episodes" >Episodes  <b>{anime.episodes} b>div>
          <div  dangerouslySetInnerHTML={{__html: anime.description}} >div> 
      div> 
  div>
  <hr width="75%"/>
 
   ))}
   "buttonContainer">
    { page != 1 && <button> Previous Pagebutton> } 
     "pageText"> {page}
     <button onClick={NextPage}>  Next Page button> 
   
   );

minimistic styled app

You can check out this GitHub repo for the CSS file.

Now we are able to get a list of anime films from the API. So what do we need to get them from the next page of the app?

We need to pass a variable that has a page name into the query. That's where variables in GraphQL come into the picture.

First, go to Apollo Studio and click on the arguments on the left hand side (first go to root > query >page and you'll see it):

Click on page and it'll add an argument to your query.

Also notice that in the variable page in the variables section, you can change its value and play around a little bit with it. But the data will only change according to the page.

Now we need to pass this variable into the query – and then we'll be able to display next page's anime in our app.

For that we'll be using the useState hook to keep a track of our current page's value. We also need to make a function to increment and decrement that as well.

  const [page, setPage] = useState(1);
  //this is how we would be passing the page in the query.
  const {loading, error, data} = useQuery(AnimeList , {  variables: { "page" : page } });

const NextPage = () => {
    setPage(page+1);
  }
  const PreviousPage = () => {
    setPage(page - 1);
  }

   "buttonContainer">
    { page != 1 && <button onClick={PreviousPage}> Previous Pagebutton> } 
     "pageText"> {page}
     <button onClick={NextPage}>  Next Page button>

And now we're done building our simple app with GraphQL. If you want to check out the codebase, here is the link.

Wrapping Up

In this article, we have covered some of the basic concepts to help you get started using GraphQL. Thank you for reading, and happy coding.

How to Build a GraphQL Server with Laravel GraphQL and Test It with Postman

Sule-Balogun Olanrewaju — Tue, 13 Jul 2021 07:54:34 +0000

GraphQL is a query language for your API. It simplifies the process of requesting the server by providing convenient ways to query objects.

For instance, if you're using a REST API and you need a list of books, you might hit the GET /books/list endpoint for all books. Then if you need a specific book by ID, you would hit GET /book?id={id}, which means you'll be making multiple requests to the server.

But GraphQL does something called declarative data fetching, where you can ask for what you want and get a predictable result in a single request.

Awesome right? Let's see how it all works.

What we will be learning?

In this article, you'll learn the basics of GraphQL by using the Laravel GraphQL package to build a server that does the following:

Register users
Fetch all users
Get a user by ID
Fetch all posts
Fetch all posts with user relationships
Finally, as a bonus, you'll also learn how to use the super awesome Postman tool to run your query and get a real-time response

Prerequisites

Here are a few things you'll need for this tutorial:

A local server (XAMPP or WAMP)
A code editor (Sublime Text, VS Code, or Atom)
A version control system (Git)
A dependency Manager (Composer)
The Laravel GraphQL package

GraphQL Basics

Before we get started, let's go over some GraphQL fundamentals.

What is a GraphQL Schema?

A GraphQL schema describes queries, mutations, and types associated with it:

type User {
    id: ID !
    name : String !
    email : String !
    age : Int
    hobbies: [String]
    created_at : DateTime 
    updated_at : DateTime
}

In the code above, the exclamation mark on column names such as id, name, and email means that they are required fields.

You can also define various data types such as Int, String, and so on. You can also include list types and define the data type it should contain like with hobbies.

What are GraphQL Queries?

GraphQL makes it convenient to interact with data on an object. You use methods to ask for specific fields on objects and then get the expected results:

{
  user {
    name
  }
}

{
  "data": {
    "user": {
      "name": "John doe"
    }
  }
}

What are GraphQL Resolvers?

Every time you request data from a GraphQL server, it gets resolved.

Resolvers contain arguments such as an object, args, context, and info. You'll see how resolvers work while building this project.

How to Get Started with GraphQL

Installation

Set up a Laravel environment by running this command in the terminal:

composer create-project laravel/laravel graphql-laravel

If you don't have composer installed, you can get it from here.

Install the open-source graphql-laravel server package:

composer require rebing/graphql-laravel

Once the installation is finished, publish config/graphql.php:

php artisan vendor:publish --provider="Rebing\GraphQL\GraphQLServiceProvider"

And start the development server with php artisan serve:

The Laravel homepage

How to Create the Migration, Controllers, and Resource

Post

In this section, you'll create a relationship between users and posts.

To do this, you'll need to create models where you define the relationship between the entities, create migrations, and define database schemas.

php artisan make:model Post -mcr

In app/Models/User, create a hasMany relationship between users and posts:

public function posts()
{
    return $this->hasMany(Post::class);
}

And in app/models/Post, define a relationship to map users to posts:

public function user()
{
    return $this->belongsTo(User::class);
}

How to Create the Migration

In this section you'll create the migration.

Laravel already ships with a default User migration. All you need to do now is add a migration for posts:

php artisan make:migration create_post_table

This creates a migration file with the database/migrations direction. Within the migration file, define the schema:

Schema::create('posts', function (Blueprint $table) {
            $table->id();
             $table->integer('user_id')->unsigned();
            $table->string('title');
            $table->text('comment');
            $table->timestamps();
        });

Next, modify the existing .env to name the database and establish a connection:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=graphql-laravel
DB_USERNAME=root
DB_PASSWORD=

Run the migrate command to create the User and Post tables:

 php artisan migrate

You can generate random records for the User and Post tables using Laravel factories.

Since Laravel ships with a default User factory, you can use that and focus on creating a Post factory.

How to Create a Post Factory

php artisan make:factory PostFactory

Once PostFactory gets created within the database > factories directory, you'll have to define the column names and the fakers you need within the definition method:

use Illuminate\Support\Str;


public function definition()
    {
        return [
            'user_id' => rand(1,5),
            'title' => $this->faker->name(),
            'comment' => $this->faker->realText(180)
        ];
    }

How to Make the Database Seeder

Within the seeder class, create an execution instance for both User and Post factories.

This will create five users and five posts with corresponding user_id's:

public function run()
    {
        \App\Models\User::factory(5)->create();

        \App\Models\Post::factory(5)->create();
    }

Then run the artisan seeder command:

php artisan db:seed

Once you run that command in the terminal, check the database tables (User and Post):

Post table

User table

How to Create a User Query

As of the time of writing this article, the Laravel GraphQL package doesn't support creating a scaffold for queries via the terminal.

So add the following to app > GraphQL > Type > UserType.php:



namespace App\GraphQL\Type;

use App\Models\User;
use GraphQL\Type\Definition\Type;
use Rebing\GraphQL\Support\Type as GraphQLType;

class UserType extends GraphQLType
{
    protected $attributes = [
        'name'          => 'User',
        'description'   => 'A user',
        'model'         => User::class,
    ];

    public function fields(): array
    {
        return [
            'id' => [
                'type' => Type::nonNull(Type::int()),
                'description' => 'The id of the user',
            ],
            'name' => [
                'type' => Type::nonNull(Type::string()),
                'description' => 'The name of user',
            ],
            'email' => [
                'type' => Type::nonNull(Type::string()),
                'description' => 'The email of user'
            ],
        ];
    }
}

In the code snippet above, you add the namespace you need to the User model. You also include a protected $attributes array that describes the model.

You also added a public field function that returns an array.

Within this function, you define the schema to include columns you specified in the user table (id, name, email).

Type::nonNull(Type::string()) is the exclamation mark indicating the required fields and string data type.

How to Add a Type to the Config

Add the UserType to the config file you created earlier: app > config > graphql.php:

'types' => [
        App\GraphQL\Type\UserType::class
    ],

How to Define the User Query

Next, you'll need to define a query that returns the UserType or a list. You also need to specify the arguments you'll use within the resolve method:



namespace App\GraphQL\Type;

use GraphQL;
use App\Models\User;
use GraphQL\Type\Definition\Type;
use Rebing\GraphQL\Support\Type as GraphQLType;

class UserType extends GraphQLType
{
    protected $attributes = [
        'name'          => 'User',
        'description'   => 'A user',
        'model'         => User::class,
    ];

    public function type(): Type
    {
        return Type::nonNull(Type::listOf(Type::nonNull(GraphQL::type('User'))));
    }

    public function args(): array
    {
        return [
            'id' => [
                'type' => Type::nonNull(Type::int()),
                'description' => 'The id of the user',
            ],
            'name' => [
                'type' => Type::nonNull(Type::string()),
                'description' => 'The name of user',
            ],
            'email' => [
                'type' => Type::nonNull(Type::string()),
                'description' => 'The email of user',
            ]
        ];
    }

    public function resolve($root, $args)
    {        
        if (isset($args['id'])) {
            return User::whereId($args['id'])->get();
        }

        if (isset($args['name'])) {
            return User::whereName($args['name'])->get();
        }

        if (isset($args['email'])) {
            return User::whereEmail($args['email'])->get();
        }

        return User::all();
    }
}

In the snippet above, you use the required namespace the package ships with together with App\Models\User.

You also extend the GraphQLType from the Laravel package, and define the attributes as a protected array.

The args method returns an ID, name, and email from the User model.

The resolve method is used to retrieve the data from the database. If there are args, then the if block gets executed and helps you filter based on user requests.

Otherwise, all the data from the User model is retrieved.

How to Add a Query to the Config

Add the following query to the app > config > graphql.php configurations file:

'schemas' => [
        'default' => [
            'query' => [
                App\GraphQL\Query\UsersQuery::class,
            ],
            'mutation' => [
                // ExampleMutation::class,
            ],
            'types' => [
                // ExampleType::class,
            ],
            'middleware' => [],
            'method' => ['get', 'post'],
        ],
    ],

You should now be able to query data from this endpoint: http://localhost:8000/graphql.

And in case you're curious, /graphql is the prefix for the route.

How to Query to Fetch all Users

For this query:

query {
    users {
        id, name , email
    }
}

Here's the expected output with Postman:

Fetch all Users

How to Create a Post Relationship with the User

Now you need to define a PostType.

This approach follows what you defined earlier for UserType.

Navigate to app > Type > PostType.php and add the following:



namespace App\GraphQL\Type;

use GraphQL;
use App\Models\Post;
use GraphQL\Type\Definition\Type;
use Rebing\GraphQL\Support\Type as GraphQLType;

class PostType extends GraphQLType
{
    protected $attributes = [
        'name'          => 'Post',
        'description'   => 'A post',
        'model'         => Post::class,
    ];

    public function args(): array
    {
        return [
            'id' => [
                'type' => Type::nonNull(Type::int()),
                'description' => 'The id of the post',
            ],
            'title' => [
                'type' => Type::nonNull(Type::string()),
                'description' => 'The title of post',
            ],
        ];
    }
}

Post follows the specification defined for User. Here you also used the namespace of the query, and also used the Post model.

With the code above, you extend the Query on the PostQuery class and set the $attributes array to be protected. And you have a fields function that returns and array with the ID, title, and comment.

Finally, you have a type within the args function that shows their various data types int or string with a description that tells you what they do at a glance.

How to Create a PostsQuery

Add the following to app > GraphQL > Query > PostsQuery.php:

 

namespace App\GraphQL\Query;

use Closure;
use App\Models\Post;
use Rebing\GraphQL\Support\Facades\GraphQL;
use GraphQL\Type\Definition\ResolveInfo;
use GraphQL\Type\Definition\Type;
use Rebing\GraphQL\Support\Query;

class PostsQuery extends Query
{
    protected $attributes = [
        'name' => 'posts',
    ];

    public function type(): Type
    {
        return Type::nonNull(Type::listOf(Type::nonNull(GraphQL::type('Post'))));
    }

    public function args(): array
    {
        return [
            'id' => [
                'name' => 'id', 
                'type' => Type::int(),
            ],
            'title' => [
                'name' => 'title', 
                'type' => Type::string(),
            ]
        ];
    }

    public function resolve($root, $args)
    {        
        if (isset($args['id'])) {
            return Post::whereId($args['id'])->get();
        }

        if (isset($args['title'])) {
            return Post::whereTitle($args['title'])->get();
        }

        return Post::all();
    }
}

In the code above, you use the resolve method to retrieve data from the database like I mentioned earlier.

If there are args, then the if block gets executed and helps you filter based on the user request. Otherwise, all the data from the Post model is returned.

How to Add PostsQuery and PostType to Config

'schemas' => [
        'default' => [
            'query' => [
                App\GraphQL\Query\UsersQuery::class,
                App\GraphQL\Query\PostsQuery::class
            ],
            'mutation' => [
                // ExampleMutation::class,
            ],
            'types' => [
                // ExampleType::class,
            ],
            'middleware' => [],
            'method' => ['get', 'post'],
        ],
    ],

'types' => [
        App\GraphQL\Type\UserType::class,
        App\GraphQL\Type\PostType::class
    ],

Now you can use the following query to get all posts:

query{
    posts{
        id
        user_id
        title
        comment
    }
}

Image of Fetch all post

You can also fetch users with post relationships with this query:

query{
    users{
        id 
        name
        posts {
            title
        }
    }
}

Image to fetch users with post relationship

How to Create a Mutation

Now you'll set up a mutation to create a user. This mutation will help with operations that involve modifying state on the server.

In your case you'll be mutating the state of the server by creating a user.

Create a mutation folder within the app directory, app > Mutation > CreateUserMutation.php.

Then add the following code to CreateUserMutation.php:



namespace App\GraphQL\Mutation;

use Closure;
use App\Models\User;
use GraphQL;
use GraphQL\Type\Definition\Type;
use GraphQL\Type\Definition\ResolveInfo;
use Rebing\GraphQL\Support\Mutation;

class CreateUserMutation extends Mutation
{
    protected $attributes = [
        'name' => 'users'
    ];

    public function type(): Type
    {
        return Type::nonNull(GraphQL::type('User'));
    }

    public function args(): array
    {
        return [
            'name' => ['
                name' => 'name', 
                'type' => Type::nonNull(Type::string()),
            ],
            'email' => ['
                name' => 'email', 
                'type' => Type::nonNull(Type::string()),
            ],
            'password' => [
                'name' => 'password', 
                'type' => Type::nonNull(Type::string()),
            ]
        ];
    }

    public function resolve($root, $args, $context, ResolveInfo $resolveInfo, Closure $getSelectFields)
    {
        return User::firstOrCreate(
            [   'email' => $args['email']],
            [   'name' => $args['name'],
                'password' => bcrypt($args['password'])
            ]);
    }
}

The resolve method helps users of the application sign up and create their record. resolve accepts args as a parameter and then uses the firstOrCreate method to ensure all users registering have a unique identifier, in this case, their email address.

In the config, you'll also need to include the mutation you just created:

'schemas' => [
        'default' => [
            'query' => [
                App\GraphQL\Query\UsersQuery::class,
                App\GraphQL\Query\PostsQuery::class
            ],
            'mutation' => [
                App\GraphQL\Mutation\CreateUserMutation::class,
            ],
            'types' => [],
            'middleware' => [],
            'method' => ['get', 'post'],
        ],
    ],

And here's how to create a user:

mutation{
    users(name : "John Doe", email : "Johndoe@gmail.com", password : "John1234"){
        id
        name
    }
}

Image of user creation

Conclusion

Congrats! You've successfully built a GraphQL server using Laravel, and ran queries with Postman to get responses. Now that you know the basics of GraphQL, I hope you use it in your projects going forward.

All the code in this tutorial is available on GitHub, which also includes the Postman collection.

Resources

How to Build a GraphQL API Using Laravel

Tamerlan Gudabayev — Wed, 26 May 2021 16:34:32 +0000

In this article, I'll walk you through how to set up your own GraphQL API using PHP and Laravel.

Two years ago, I started working professionally as a backend developer. And I was very intimidated by all the technology I didn't yet know. Words like Docker, Kubernetes, and GraphQL seemed quite scary.

But I mustered up the courage and started to learn them all one by one.

It was actually easier than I thought, so I would like to share with you what I've learned about GraphQL by creating a simple demo project together.

You can find the final project on GitHub here.

Prerequisites

Before we begin, make sure to have these installed on your system:

PHP 7+
Composer 2.0
Docker 20.10.6 (Any other version should be fine)
Docker-Compose 1.29.1 (Any other version should be fine)

I also assume that you have:

Basic knowledge of Laravel (Eloquent, Migrations, MVC, Routes, and so on)
Knowledge of PHP (Syntax, OOP, and so on)
Basic knowledge of GraphQL (in theory)

What We're Going to Build

I like RPG games like the Elder Scrolls Series or Final Fantasy, so of course our app will be about games. The project will consist of only two models called Quests and Categories.

Database Schema

By the end of this post we will create a CRUD GraphQL API for each model.

How to Initialize the Project

Create a Laravel project using this command:

composer create-project laravel/laravel quest_journal

This will create a new project in a new directory called quest_journal.

Next let's setup sail like this:

# Move into the project
cd quest_journal

# Install and configure laravel sail
php artisan sail:install

It's gonna ask you which services to install. Just press enter to only install MySQL.

If all goes well, you should now see a docker-compose.yml file in your project directory.

Let's then run the containers using sail:

# Run the containers
./vendor/bin/sail up -d

# Check if the containers are running
docker ps

At this point I suggest you alias sail to ./vendor/bin/sail. You can do that by adding this piece of code to your bashrc or zshrc:

# in ~./zshrc or ~./bashrc

alias sail = 'bash vendor/bin/sail'

Moving on, if you go to localhost you should see something like this:

Default Laravel Home Page

But before we move on, there are some packages that we need to install first:

# IDE helper for laravel, always useful to have.
sail composer require --dev barryvdh/laravel-ide-helper

# GraphQL library which we are going to use
sail composer require rebing/graphql-laravel

Next we have to publish the GraphQL library like this:

sail artisan vendor:publish --provider="Rebing\\GraphQL\\GraphQLServiceProvider"

This should create a GraphQL config file that we will use in config/graphql.php.

How to Create the Migrations and Models

This isn't a Laravel tutorial, so we'll quickly create the models with the appropriate migrations.

Let's start with category model:

# Create model with migrations
sail artisan make:model -m Category

This will create the Category model with it's migration file.

Our category will consist of four fields:

ID
Title
Created_At
Updated_At

Our category migrations file should look like this:



// database/migrations/yyyy_mm_dd_hhMMss_create_categories_table.php

use Illuminate\\Database\\Migrations\\Migration;
use Illuminate\\Database\\Schema\\Blueprint;
use Illuminate\\Support\\Facades\\Schema;

class CreateCategoriesTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('categories', function (Blueprint $table) {
            $table->id();
            $table->text('title');
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists('categories');
    }
}

Next let's configure the category model class.

We will do two things here:

Make the field title editable, so we will add it to our $fillable array.
Define the relationship between category model and quest model.



// App\\Models\\Category

namespace App\\Models;

use Illuminate\\Database\\Eloquent\\Factories\\HasFactory;
use Illuminate\\Database\\Eloquent\\Model;

class Category extends Model
{
    use HasFactory;

    protected $fillable = ['title'];

    public function quests(){
        return $this->hasMany(Quest::class);
    }
}

You will have some errors concerning the Quest model, but no worries – we will handle that next.

Run the command to make a model and migration file for quest:

sail artisan make:model -m Quest

This will create a model named Quest and a migration file for it.

Our quest will have the fields:

ID
Title
Description
Reward
Category_ID
Created_At
Updated_At


// database/migrations/yyyy_mm_dd_hhMMss_create_quests_table.php

use Illuminate\\Database\\Migrations\\Migration;
use Illuminate\\Database\\Schema\\Blueprint;
use Illuminate\\Support\\Facades\\Schema;

class CreateQuestsTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('quests', function (Blueprint $table) {
            $table->id();
            $table->text('title');
            $table->text('description');
            $table->integer('reward');
            $table->foreignId('category_id')->constrained();
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists('quests');
    }
}

As you can see, we declared the category_id to be a foreignId. This way Laravel will automatically create a foreign key relationship between the tables categories and quests.

Next let's configure the quest model class.

Here we will:

Make the appropriate fields editable by adding them to the $fillable array.
Define the relationship between category model and quest model.



// App\\Models\\Quest

namespace App\\Models;

use Illuminate\\Database\\Eloquent\\Factories\\HasFactory;
use Illuminate\\Database\\Eloquent\\Model;

class Quest extends Model
{
    use HasFactory;

    protected $fillable = ['title', 'category_id', 'description',                               'reward'];

    public function category(){
        return $this->belongsTo(Category::class);
    }
}

With both the migrations and models ready, we can apply the changes to the database.

Run this command:

# Apply migrations
sail artisan migrate

Our database should be updated! Next we should put some data into our tables.

How to Seed the Database

We need data to work with, but as developers we are too lazy to manually do it.

This is where factories come.

First, we'll create the factory classes for both the quest and category model.

Run the following commands:

# Create a factory class for quest model
sail artisan make:factory QuestFactory --model=Quest

# Create a factory class for category model
sail artisan make:factory CategoryFactory --model=Category

This will create for us two new classes:

QuestFactory – a class that helps us generate quests.
CategoryFactory – a class that helps us generate categories.

Let's start with the QuestFactory. In our definitions function we will tell Laravel how each field should be generated. For the field category_id, we will pick a random category.



// database/factories/QuestFactory.php

namespace Database\\Factories;

use App\\Models\\Category;
use App\\Models\\Quest;
use Illuminate\\Database\\Eloquent\\Factories\\Factory;

class QuestFactory extends Factory
{
    /**
     * The name of the factory's corresponding model.
     *
     * @var string
     */
    protected $model = Quest::class;

    /**
     * Define the model's default state.
     *
     * @return array
     */
    public function definition()
    {
        $categoryIDs = Category::all()->pluck('id')->toArray();

        return [
            'title' => $this->faker->title(),
            'description' => $this->faker->text(),
            'reward' => $this->faker->numberBetween(1 , 100),
            'category_id' => $this->faker->randomElement($categoryIDs)
        ];
    }
}

CategoryFactory is much simpler, as we simply have to generate a title.



// database/factories/CategoryFactory.php

namespace Database\\Factories;

use App\\Models\\Category;
use Illuminate\\Database\\Eloquent\\Factories\\Factory;

class CategoryFactory extends Factory
{
    /**
     * The name of the factory's corresponding model.
     *
     * @var string
     */
    protected $model = Category::class;

    /**
     * Define the model's default state.
     *
     * @return array
     */
    public function definition()
    {
        return [
            'title' => $this->faker->title()
        ];
    }
}

Now instead of creating seeders, we will simply run the factory create method inside DatabaseSeeder.php:



// database/seeders/DatabaseSeeder.php

namespace Database\\Seeders;

use App\\Models\\Category;
use App\\Models\\Quest;
use Illuminate\\Database\\Seeder;

class DatabaseSeeder extends Seeder
{
    /**
     * Seed the application's database.
     *
     * @return void
     */
    public function run()
    {
        Category::factory(10)->create();
        Quest::factory(10)->create();
    }
}

Finally run the command to seed the database.

sail artisan db:seed

Folder Structure

At this point we are ready to create our GraphQL APIs. To do that let's first create a new folder in the app directory called GraphQL.

Inside the GraphQL folder, create three new folders:

Mutations
Queries
Types

It will look something like this:

This is where the bulk of our code will be. As you might be able to tell, it's very different from REST architecture. Before we begin writing the code, let me quickly explain the purpose of each folder.

Mutations: This folder will contain classes that manage the insert, update, and delete operations.
Queries: This folder will contain the classes that fetch data from the database.
Types: You can think of this as a model, or a model resource. Basically types are objects that can be fetched from the database. For example, we are going to have a QuestType and a CategoryType.

How to Define the Category and Quest Types

Let's first start with types. We'll create two new classes in our types folder called:

CategoryType
QuestType

Here is where we will use the rebing/graphql-laravel package which basically helps us create types, queries, and mutations.

Our types will inherit the Type class from Rebing\\GraphQL\\Support\\Type. There's also another class called Type in the package but it's used to declare the type of field (like string, int, and so on).

Let's begin with the CategoryType class:



// app/graphql/types/CategoryType 

namespace App\\GraphQL\\Types;

use App\\Models\\Category;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Type as GraphQLType;

class CategoryType extends GraphQLType
{
    protected $attributes = [
        'name' => 'Category',
        'description' => 'Collection of categories',
        'model' => Category::class
    ];

    public function fields(): array
    {
        return [
            'id' => [
                'type' => Type::nonNull(Type::int()),
                'description' => 'ID of quest'
            ],
            'title' => [
                'type' => Type::nonNull(Type::string()),
                'description' => 'Title of the quest'
            ],
            'quests' => [
                'type' => Type::listOf(GraphQL::type('Quest')),
                'description' => 'List of quests'
            ]
        ];
    }
}

Let's break this down:

Attributes: This is your type configuration. It has core information about your type, and to which model it associates.
Fields: This method returns the fields that your client can ask for.

You may have noticed that we have a field called quests which is a list of QuestType. But we don't associate the class directly – we instead use its name from its attribute.

Next is the QuestType class:



// app/graphql/types/QuestType 

namespace App\\GraphQL\\Types;

use App\\Models\\Quest;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Type as GraphQLType;

class QuestType extends GraphQLType
{
    protected $attributes = [
        'name' => 'Quest',
        'description' => 'Collection of quests with their respective category',
        'model' => Quest::class
    ];

    public function fields(): array
    {
        return [
            'id' => [
                'type' => Type::nonNull(Type::int()),
                'description' => 'ID of quest'
            ],
            'title' => [
                'type' => Type::nonNull(Type::string()),
                'description' => 'Title of the quest'
            ],
            'description' => [
                'type' => Type::nonNull(Type::string()),
                'description' => 'Description of quest'
            ],
            'reward' => [
                'type' => Type::nonNull(Type::int()),
                'description' => 'Quest reward'
            ],
            'category' => [
                'type' => GraphQL::type('Category'),
                'description' => 'The category of the quest'
            ]
        ];
    }
}

How to Define the Queries for Your Model

Now that we have defined our types, we can move on to queries.

For each model we will have two queries:

A class to query a single model
A class to query a list of models

To keep stuff organized, create two new folders in your Queries folder:

Category
Quest

Let's create our classes:

QuestQuery
QuestsQuery
CategoryQuery
CategoriesQuery

Your file structure should look like this:

Let's start with the QuestQuery class:



// app/graphql/queries/quest/QuestQuery 

namespace App\\GraphQL\\Queries\\Quest;

use App\\Models\\Quest;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Query;

class QuestQuery extends Query
{
    protected $attributes = [
        'name' => 'quest',
    ];

    public function type(): Type
    {
        return GraphQL::type('Quest');
    }

    public function args(): array
    {
        return [
            'id' => [
                'name' => 'id',
                'type' => Type::int(),
                'rules' => ['required']
            ]
        ];
    }

    public function resolve($root, $args)
    {
        return Quest::findOrFail($args['id']);
    }
}

Let's break this down:

Our query classes will inherit from Rebing\\GraphQL\\Support\\Query
The attributes function is used as the query configuration.
The type function is used to declare what type of object this query will return.
The args function is used to declare what arguments this query will accept. In our case we only need the id of the quest.
The resolve function does the bulk of the work – it returns the actual object using eloquent.

The rest of the classes have a similar format, so it's pretty much self explanatory.



// app/graphql/queries/quest/QuestsQuery 

namespace App\\GraphQL\\Queries\\Quest;

use App\\Models\\Quest;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Query;

class QuestsQuery extends Query
{
    protected $attributes = [
        'name' => 'quests',
    ];

    public function type(): Type
    {
        return Type::listOf(GraphQL::type('Quest'));
    }

    public function resolve($root, $args)
    {
        return Quest::all();
    }
}



// app/graphql/queries/category/CategoryQuery 

namespace App\\GraphQL\\Queries\\Category;

use App\\Models\\Category;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Query;

class CategoryQuery extends Query
{
    protected $attributes = [
        'name' => 'category',
    ];

    public function type(): Type
    {
        return GraphQL::type('Category');
    }

    public function args(): array
    {
        return [
            'id' => [
                'name' => 'id',
                'type' => Type::int(),
                'rules' => ['required']
            ]
        ];
    }

    public function resolve($root, $args)
    {
        return Category::findOrFail($args['id']);
    }
}



// app/graphql/queries/category/CategoriesQuery 

namespace App\\GraphQL\\Queries\\Category;

use App\\Models\\Category;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Query;

class CategoriesQuery extends Query
{
    protected $attributes = [
        'name' => 'categories',
    ];

    public function type(): Type
    {
        return Type::listOf(GraphQL::type('Category'));
    }

    public function resolve($root, $args)
    {
        return Category::all();
    }
}

How to Create the Mutation Classes

Mutations will house our classes that control the insertion/deletion of our models. So for each model we will have three classes:

A class to create a model
A class to update a model
A class to delete a model

We have two models in our app, so we will have 6 mutation classes.

To keep things organized, create two new folders in your Mutations folder:

Category
Quest

Let's create our mutation classes:

CreateCategoryMutation
DeleteCategoryMutation
UpdateCategoryMutation
CreateQuestMutation
DeleteQuestMutation
UpdateQuestMutation

Your file structure should look like this:

Let's start with CreateCategoryMutation:



// app/graphql/mutations/category/CreateCategoryMutation 

namespace App\\GraphQL\\Mutations\\Category;

use App\\Models\\Category;
use Rebing\\GraphQL\\Support\\Mutation;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;

class CreateCategoryMutation extends Mutation
{
    protected $attributes = [
        'name' => 'createCategory',
        'description' => 'Creates a category'
    ];

    public function type(): Type
    {
        return GraphQL::type('Category');
    }

    public function args(): array
    {
        return [
            'title' => [
                'name' => 'title',
                'type' =>  Type::nonNull(Type::string()),
            ],
        ];
    }

    public function resolve($root, $args)
    {
        $category = new Category();
        $category->fill($args);
        $category->save();

        return $category;
    }
}

As you can see, the structure is very similar to our queries.

Once again let's break down this class:

Our mutation classes will inherit from Rebing\\GraphQL\\Support\\Mutation
The attributes function is used as mutation configuration.
The type function is used to declare what type of object this query will return.
The args function is used to declare what arguments this mutation will accept. In our case we only need the title field.
The resolve function does the bulk of the work – it does the actual mutation using eloquent.

The rest of the mutations have a similar format, so they should be self-explanatory.



// app/graphql/mutations/category/DeleteCategoryMutation 

namespace App\\GraphQL\\Mutations\\Category;

use App\\Models\\Category;
use Rebing\\GraphQL\\Support\\Mutation;
use GraphQL\\Type\\Definition\\Type;

class DeleteCategoryMutation extends Mutation
{
    protected $attributes = [
        'name' => 'deleteCategory',
        'description' => 'deletes a category'
    ];

    public function type(): Type
    {
        return Type::boolean();
    }

    public function args(): array
    {
        return [
            'id' => [
                'name' => 'id',
                'type' => Type::int(),
                'rules' => ['required']
            ]
        ];
    }

    public function resolve($root, $args)
    {
        $category = Category::findOrFail($args['id']);

        return  $category->delete() ? true : false;
    }
}



// app/graphql/mutations/category/UpdateCategoryMutation 

namespace App\\GraphQL\\Mutations\\Category;

use App\\Models\\Category;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Mutation;

class UpdateCategoryMutation extends Mutation
{
    protected $attributes = [
        'name' => 'updateCategory',
        'description' => 'Updates a category'
    ];

    public function type(): Type
    {
        return GraphQL::type('Category');
    }

    public function args(): array
    {
        return [
            'id' => [
                'name' => 'id',
                'type' =>  Type::nonNull(Type::int()),
            ],
            'title' => [
                'name' => 'title',
                'type' =>  Type::nonNull(Type::string()),
            ],
        ];
    }

    public function resolve($root, $args)
    {
        $category = Category::findOrFail($args['id']);
        $category->fill($args);
        $category->save();

        return $category;
    }
}



// app/graphql/mutations/quest/CreateQuestMutation 

namespace App\\GraphQL\\Mutations\\Quest;

use App\\Models\\Quest;
use Rebing\\GraphQL\\Support\\Mutation;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;

class CreateQuestMutation extends Mutation
{
    protected $attributes = [
        'name' => 'createQuest',
        'description' => 'Creates a quest'
    ];

    public function type(): Type
    {
        return GraphQL::type('Quest');
    }

    public function args(): array
    {
        return [
            'title' => [
                'name' => 'title',
                'type' =>  Type::nonNull(Type::string()),
            ],
            'description' => [
                'name' => 'description',
                'type' =>  Type::nonNull(Type::string()),
            ],
            'reward' => [
                'name' => 'reward',
                'type' => Type::nonNull(Type::int()),
            ],
            'category_id' => [
                'name' => 'category_id',
                'type' => Type::nonNull(Type::int()),
                'rules' => ['exists:categories,id']
            ]
        ];
    }

    public function resolve($root, $args)
    {
        $quest = new Quest();
        $quest->fill($args);
        $quest->save();

        return $quest;
    }
}



// app/graphql/mutations/quest/DeleteQuestMutation 

namespace App\\GraphQL\\Mutations\\Quest;

use App\\Models\\Quest;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Mutation;

class DeleteQuestMutation extends Mutation
{
    protected $attributes = [
        'name' => 'deleteQuest',
        'description' => 'Deletes a quest'
    ];

    public function type(): Type
    {
        return Type::boolean();
    }

    public function args(): array
    {
        return [
            'id' => [
                'name' => 'id',
                'type' => Type::nonNull(Type::int()),
                'rules' => ['exists:quests']
            ]
        ];
    }

    public function resolve($root, $args)
    {
        $category = Quest::findOrFail($args['id']);

        return  $category->delete() ? true : false;
    }
}



// app/graphql/mutations/quest/UpdateQuestMutation 

namespace App\\GraphQL\\Mutations\\Quest;

use App\\Models\\Quest;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Mutation;

class UpdateQuestMutation extends Mutation
{
    protected $attributes = [
        'name' => 'updateQuest',
        'description' => 'Updates a quest'
    ];

    public function type(): Type
    {
        return GraphQL::type('Quest');
    }

    public function args(): array
    {
        return [
            'id' => [
                'name' => 'id',
                'type' =>  Type::nonNull(Type::int()),
            ],
            'title' => [
                'name' => 'title',
                'type' =>  Type::nonNull(Type::string()),
            ],
            'description' => [
                'name' => 'description',
                'type' =>  Type::nonNull(Type::string()),
            ],
            'reward' => [
                'name' => 'reward',
                'type' => Type::nonNull(Type::int()),
            ],
            'category_id' => [
                'name' => 'category_id',
                'type' => Type::nonNull(Type::int()),
                'rules' => ['exists:categories,id']
            ]
        ];
    }

    public function resolve($root, $args)
    {
        $quest = Quest::findOrFail($args['id']);
        $quest->fill($args);
        $quest->save();

        return $quest;
    }
}

Schemas

All the hard work is done! Now we have to put everything together.

We have to register our queries, mutations, and types in our config/graphql:



return [
    // ... some code

    'schemas' => [
        'default' => [
            'query' => [
                'quest' => \\App\\GraphQL\\Queries\\Quest\\QuestQuery::class,
                'quests' => \\App\\GraphQL\\Queries\\Quest\\QuestsQuery::class,
                'category' => \\App\\GraphQL\\Queries\\Category\\CategoryQuery::class,
                'categories' => \\App\\GraphQL\\Queries\\Category\\CategoriesQuery::class,
            ],
            'mutation' => [
                'createQuest' => \\App\\GraphQL\\Mutations\\Quest\\CreateQuestMutation::class,
                'updateQuest' => \\App\\GraphQL\\Mutations\\Quest\\UpdateQuestMutation::class,
                'deleteQuest' => \\App\\GraphQL\\Mutations\\Quest\\DeleteQuestMutation::class,
                'createCategory' => \\App\\GraphQL\\Mutations\\Category\\CreateCategoryMutation::class,
                'updateCategory' => \\App\\GraphQL\\Mutations\\Category\\UpdateCategoryMutation::class,
                'deleteCategory' => \\App\\GraphQL\\Mutations\\Category\\DeleteCategoryMutation::class,
            ],
            'middleware' => [],
            'method' => ['get', 'post'],
        ],
    ],

        'types' => [
       'Quest' => \\App\\GraphQL\\Types\\QuestType::class,
       'Category' => \\App\\GraphQL\\Types\\CategoryType::class
    ],

    // some code 
];

Now that all that's done, let's try out our APIs.

How to Test the Queries

Our GraphQL library provides us with an IDE.

So make sure your Docker containers are running and head into http://localhost/graphiql.

You should see something like this:

Let us test our queries:

Fetch a Single Quest

Fetch a List of Quests

Insert a Quest into the Database

Update a Quest

Delete a Quest from the Database

Conclusion

Congratulations, you have created your first GraphQL API.

In summary:

A GraphQL API consists of three parts: Queries, Types, and Mutations.
Mutations manage your CRUD operations.
Queries fetch from the database.
Types are the model resource that gets returned to the client.

Thank you for reading!

GraphQL - freeCodeCamp.org

How to Use GraphQL in Flutter: A Handbook for Developers

Table of Contents

Prerequisites

What is GraphQL?

Why Facebook Built It

Understanding the Problem: Life Before GraphQL

How REST Works

Over-fetching: Too Much Data

Under-fetching: Not Enough Data

Versioning: When APIs Can't Evolve Cleanly

The Single Endpoint Approach

One Endpoint, Client-Defined Data

Why GraphQL Doesn't Need Versioning

Core GraphQL Concepts: A Deep Dive

The Schema: The Contract Between Client and Server

Types: The Building Blocks

Queries: Reading Data

Mutations: Changing Data

Subscriptions: Real-Time Data

Variables: Making Queries Safe and Reusable

Fragments: Reusable Field Sets

Resolvers: How the Server Fulfills Queries

GraphQL Architecture in Flutter

How the Pieces Connect

The Normalized Cache: GraphQL's Secret Weapon

Setting Up GraphQL in Flutter

Adding the Dependency

Android Build Configuration

Initializing Hive for Persistent Caching

Creating the GraphQL Client

Adding WebSocket Support for Subscriptions

Using GraphQL in Flutter: Queries, Mutations, and Subscriptions

Queries: Fetching and Displaying Data

Using Hooks for Queries

Mutations: Triggering Data Changes

Subscriptions: Receiving Real-Time Events

Advanced Concepts

Caching Strategies: Choosing the Right Policy

Pagination with fetchMore

Optimistic UI Updates

Error Handling: A Production-Grade Approach

Authentication: Transparent Token Refresh

Best Practices in Real Apps

Project Structure That Scales

Composing Queries from Fragments

Parsing GraphQL Data into Typed Models

Integrating with Bloc and a Repository Layer

When to Use GraphQL and When Not To

Where GraphQL Excels

Where GraphQL is the Wrong Choice

Common Mistakes

Ignoring How the Normalized Cache Works

Defining Query Strings Inside the Build Method

Using networkOnly for Everything

Forgetting to Cancel Subscriptions

Not Handling Partial GraphQL Results

Mini End-to-End Example

The GraphQL Client

The Queries

The Mutations

The Entry Point

The Repos Screen

Conclusion

References

Official Package Documentation

GraphQL Language and Specification

Tooling and Ecosystem

Related Flutter Packages

Learning Resources

How to Build a GraphQL API in Django

Here’s what we’ll cover:

What Is GraphQL, and Why Does It Matter?

What You’ll Need Before You Start

How to Build a GraphQL API in Django

1. Install Graphene-Django

2. Add a Simple Model

3. Create a Schema

How to Add Mutations (Also Known As Writing Data)

Code Walkthrough: Creating a Post via Mutation in GraphQL

Using `networkOnly` for Everything

Step 1: The `CreatePost` Mutation Class