DEV Community: Open GraphQL

Feature Flag approach with GraphQL and React 🕹

Rafael Nunes — Mon, 25 May 2020 03:51:35 +0000

Feature flag (or feature toggle, feature switch…) comes with different shapes and implementations, however, is a well known and powerful technique for allowing teams to modify system behaviour without changing code.

The idea is to be able to enable or disable features during execution time without any deploy. That is a powerful tool with various implementations across different languages, the applications are many: A/B testing, toggle app configuration, delivery new features gradually, etc.

Storage

While having feature flags is very handy they introduce complexity starting by the management of the flags. That is one of the reasons why you will find managed services like Optimizely, Rollout, and others. In addition to the feature, they offer a lot more like analytics, and targeting.

It does not mean that you need a third-party app or integration to start using feature flags. In fact, every tool and approach should be considered depending on what do you need at the implementation moment.

You may opt-in for a managed service or manage your own feature flags in your own database as well.

API

So once you have decided how to manage the flags we need to expose them in our GraphQL API. The objective is always to strive for making your schema self contained and easy to understand, ideally, it should not reflect the way it is stored in the database (although it can).

We want to expose the features available for some user, app or instance. A query that provides that information could look like the following:

type Query {
  enabledFeatures: [Feature!]!
}

type Feature {
  name: String!
}

In the schema above, we are defining two important units in our domain, they are:

Feature and enabledFeatures. Feature is a representation of the feature you want to switch on and off and it only contains a name at the moment.
enabledFeatures is a query that returns an array of Feature.

We only return the features enabled so whoever is consuming the API does not need to know the entire set of features. The lack of some feature in the array means that the feature is not visible/available.

Note: In the backend, you can identify the user through headers such as Authorization and filter features for that user. Or filter based in any other information in the request, for example, User Agent.

You can see this schema being served live on this API sandbox. I'm using Apollo Server in the example.

Querying

Having the contract defined we are now able to fetch features. You can play around on the playground built in the sandbox example.

query {
  enabledFeatures {
    name
  }
}

In the React application, I will be using Apollo Client as I'm familiar with the API, but it does not matter the library you use. You can follow along with the implementation of this client sandbox.

A component that queries all the features would look like the following:

const QUERY = gql`
  query {
    enabledFeatures {
      name
    }
  }
`;

function BasicQuery() {
  const { loading, error, data } = useQuery(QUERY);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error :</p>;

  return (
    <div>
      <h2>List of features:</h2>
      <ul>
        {data.enabledFeatures.map(feature => (
          <li key={feature.name}>
            <p>{feature.name}</p>
          </li>
        ))}
      </ul>
    </div>
  );
}

Having that is a good start point, right know you already have a way to query all the features and you can make use of it to dynamically turn something on and off. So let's make that.

useFeatureFlag

I want to guard a component so every time the user hit that part of the code we only render it if the feature is enabled. To avoid writing this logic over and over again I'm going to build a hook (previously I've used render props, but you can also make it a HOC component, you can work with whatever suits you prefer). The hook gets a feature name it checks if that is enabled and returns the status to the caller.

function useFeature(name) {
  const { loading, error, data } = useQuery(QUERY);

  let feature = {
    loading,
    error,
  };

  if (!data) return feature;

  const enabled = data.enabledFeatures.some(feature => feature.name === name);
  feature.enabled = enabled;

  return feature;
}

That hook uses the same query we used before and it will return whether or not the passed name is present in the list of features, as well as loading and error state if you want to handle the intermediate states. We can now use it in any component to switch the render output depending on it.

const Feature3 = () => {
  const name = 'feature3';
  const feature = useFeatureFlag(name);

  if (feature.loading || feature.enabled === undefined) {
    return <p>Loading {name}...</p>;
  }

  if (feature.error) return <p>Error :</p>;

  if (feature.enabled) {
    return <h2>{name} is enabled.</h2>;
  }

  return <h2>{name} is disabled.</h2>;
};

If we have only feature1 and feature2 enabled when querying feature3 we should see the disabled message. Similarly, if we query feature2 or feature1 we should see the enabled message.

Caching and better UX

Although our useFeatureFlag is enough to define if a feature is enabled, it queries enabledFeatures when the component is mounted. Depending on the application and the goal of your flag it can decrease the user experience because the user will have to wait for the query to finish.

Thankfully Apollo Client comes by default with an in-memory cache implementation! Knowing that we deduce the useFeatureFlag will be slower only on its first execution. After that, the result will be cached. However, we can go further and cache it ahead of time.

We can implement a pretty similar component to the BasicQuery what would follow the same principles as useFeatureFlag, but it is not concerned about any specific feature. It is only worried about querying them and rendering the children.

function FeatureFlags({ children }) {
  const { loading, error } = useQuery(QUERY);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error :</p>;

  return <React.Fragment>{children}</React.Fragment>;
}

You may customize the way you render by ignoring the loading state or error, depending on your needs.

It works like context providers and you could indeed use the context API to create a provider to share its features and consume them with hooks. But this approach may be good enough as well.

FeatureFlags could be placed in the top of your component tree or would wrap a portion of your App that can be controlled by the feature flags.

const App = () => (
  <ApolloProvider client={client}>
    <FeatureFlags>
      <div className="App">
        <h1>Hello Feature Flag</h1>
        <section>
          <BasicQuery />
        </section>
        <section>
          <Feature2 />
        </section>
        <section>
          <Feature3 />
        </section>
      </div>
    </FeatureFlags>
  </ApolloProvider>
);

This approach is not sophisticated, however already have some advantages like saving network calls being fired on every useFeatureFlag. Which also avoids the pending state in every guarded component. The trade-off here is to slow down the overall load in favour of the later dependants rendering way faster.

The cache consistency can be a problem if we change the feature in the backend, but the user already cached the queries. For working around that you may extend the hook to receive a fetch policy option. Apollo allows you to configure the way you interact with the cache and you can opt-in for network-only, for example. Nevertheless, the in-memory cache only lives until the page is refreshed it might not be that critical depending on your use case.

What is next?

That is my initial take when thinking about feature flags with GraphQL. The possibilities are many and as I wrote several times in this article it will depend on your use cases! So make it better work for you.

In my perception potential extensions would be:

Adding options or variations as a field of Feature, then you can branch the feature implementation depending on its variation or properties (aka A/B testing).
Making the components and hooks more generic accepting the query as props to them.
Adding a new query, featureEnabled to query the enabled status by the name directly from the backend so you do not have to filter it in the client-side.

What is your take on feature flags? 😊🙌🏽

cover image by Mikkel Bech on Unsplash
This post is a complete rewrite of feature flag approach for react using apollo client. I felt it needed an update.

Migrate from Graphcool to Hasura

Praveen Durairaju — Sat, 09 May 2020 12:29:12 +0000

Graph.cool will be sunsetted July 1, 2020. If you have an existing project, it is time to migrate off from their platform to have enough leeway for testing and going production.

I have been helping a few folks migrate from Graph.cool to Hasura and decided to put together a rough migration path.
Hasura is an open source engine that connects to your databases & microservices and auto-generates a production-ready GraphQL backend.

Pre-requisites:

We will be using docker to run some containers (MySQL, Postgres and Hasura). If you don't have docker on your machine yet, it is time to set up. Read their official docs

Note: This guide is not comprehensive and some steps require manual intervention depending on your Graph.cool project. Feel free to ask any queries in the comments. You can also DM me on Twitter. I will be happy to help you out :)

But here's roughly what you need to follow to get going.

Step 1: Export data from Graph.cool

Export your Graph.cool data using their export tool. This will give a MySQL binary dump of your current Graphcool data.

Step 2: Set up an intermediary MySQL server

We need to set up a MySQL server as an intermediary step in order to migrate data from Graph.cool to Postgres.

Step 2.1: Start MySQL with Docker

docker run --name graphcool-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -p 3306:3306 -d mysql:latest --default-authentication-plugin=mysql_native_password

Replace the password (my-secret-pw) as required.

Step 2.2: Connect to MySQL via mysql CLI

mysql --user=root --password=my-secret-pw --host=<host>

Replace the host and password as required.

Step 2.3: Create a database in MySQL

create database public;

Step 2.4: Import data

Import Graph.cool's MySQL export into your local MySQL instance:

mysql --user=root --password=my-secret-pw --host=<host> public --binary-mode=1 < <pathtomysqlexport>

Replace host and pathtomysqlexport as required. Your data should now be present in the MySQL database.

Step 3: Migrate data to Hasura

Since MySQL is now set up with all the data from Graph.cool, we need to create a Hasura and Postgres instance, and to import the data to the same.

Step 3.1: Set up Hasura

Refer to the Getting started guide to set up Hasura using docker-compose.

Step 3.2: Import data into Postgres

We will use pgloader to migrate from MySQL to Postgres. Refer to their installation guide for setting this up.

Once you have installed, execute the following command:

pgloader mysql://root:my-secret-pw@<host>/public postgresql://postgres:postgrespassword@<host>:5432/postgres

Replace <host> and mysql password (my-secret-pw) as required.

Your data should now be present in the Postgres database.

Step 3.3: Connect Hasura to Postgres

Once the dataset is migrated to Postgres, Hasura should be able to track tables and relationships.

Note: If you have enums in your Graph.cool project, check out Enums in Hasura, since they're handled differently in Hasura and you would need to change the data structure a bit.

Step 4: Migrate structure & functionality

After migrating the data to Hasura, there is some manual work involved in migrating the structure and functionality of your Graph.cool project.

Step 4.1: Restructure connection tables

You can rename tables/columns to match your client-side queries as required. Do note that, for every one-to-one relationship, Graph.cool would have created a connection table to link them. This would require a bit of manual work to restructure. Currently, there is no automation available for this step. Carefully review the connection tables and make the necessary changes.

Read up more about Relationships in Hasura

Step 4.2: Migrate functions

In case you have functions in Graph.cool, Hasura has an equivalent feature called Event Triggers. Migrating this involves taking your code and deploying it on a different platform. It could be a serverless function or all the functions can be combined into a monolith Node.js server. The choice is up to you.

Do note that for event triggers, the payload that Hasura sends might be different, and you might have to change the way the request body parameters are handled in your function code.

Step 4.3: Migrate auth

There are two ways of authenticating users in Graph.cool:

Using Auth0
Using email-password auth.

If you were using Auth0 with Graph.cool, the migration should be fairly straightforward. You can configure Hasura with Auth0 easily by following the Auth0 guide.

In case you are using email-password auth, Graph.cool generates mutations for

creating a user

createUser(authProvider: { email: { email, password } })

signinUser(email: { email, password })

You will need to implement these custom mutations using Hasura Actions.
Refer to this example for a custom signup mutation. You can modify this to include login functionality.

Step 4.4: Migrate permissions

The CRUD permissions in Graph.cool can be manually migrated to Hasura's permission system. You can define roles in Hasura and configure permissions declaratively for all the CRUD operations.
Refer to authorization for configuring Hasura permissions.

Community Tooling for File Storage

Nhost has a community maintained solution hasura-backend-plus for handling Files on Cloud providers like S3 in case you are looking for a way to migrate Files from Graph.cool. They also have an Auth solution that can be integrated with Hasura :)

Subscriptions

Hasura gives you realtime APIs out of the box. All your Postgres tables can be subscribed from the client using GraphQL Subscriptions.

I hope this guide gives an indication of the steps involved. In case you are stuck with any of the steps, do ping me :)

Hasura has an active and a helpful discord community. Do join the discord server as well and post your queries.

Building Dad Jokes using The Prisma Framework (formerly Prisma 2) and React Native

Akshay Kadam (A2K) — Wed, 15 Jan 2020 15:16:58 +0000

The Prisma Framework (formerly known as Prisma 2) is a complete rewrite of the original Prisma. It is being rewritten in Rust while the original was written in Scala. The original version had memory issues with it and it required JVM to run. It also needed an additional server to run in addition to a backend server. The newest version of Prisma does not require any such thing. With The Prisma Framework, the query engine is now a bundled executable that is run alongside the backend on the same server.

The Prisma Framework consists of 3 standalone tools to tackle the problems of data access, data migrations, and admin UI:

Photon: Type-safe and auto-generated database client ("ORM replacement")
Lift: Declarative migration system with custom workflows
Studio: Provides Admin UI to support various database workflows

So now let's get started with building a server with The Prisma Framework.

To keep it fun and corny, we will be making a Dad Jokes App.

Prerequisites

For this tutorial, you need a basic knowledge of React Native. You also need to understand React Hooks.

Since this tutorial is primarily focused on Prisma, it is assumed that you already have a working knowledge of React and its basic concepts.

Throughout the course of this tutorial, we’ll be using yarn. If you don’t have yarn already installed, install it from here.

To make sure we’re on the same page, these are the versions used in this tutorial:

Node v12.12.0
npm v6.11.3
npx v6.11.3
yarn v1.19.1
prisma2 v2.0.0-preview016.2
expo-cli v3.7.1
expo v35.0.0

Server-Side (The Prisma Framework)

Start a new Prisma 2 project

Install prisma2 CLI globally and run the init command then:

$ yarn global add prisma2 // or npm install --global prisma2
$ prisma2 init server

Run the interactive `prisma2 init` flow & select boilerplate

Select the following in the interactive prompts:

Select Starter Kit
Select JavaScript
Select GraphQL API
Select SQLite

Once terminated, the init command will have created an initial project setup in the server/ folder.

Now open the schema.prisma file and replace it with the following:

generator photon {
  provider = "photonjs"
}

datasource db {
  provider = "sqlite"
  url      = "file:dev.db"
}

model Joke {
  id   String @default(cuid()) @id
  joke String @unique
}

schema.prisma contains the data model as well as the configuration options.

Here, we specify that we want to connect to the SQLite datasource called dev.db as well as target code generators like photonjs generator.

Then we define the data model Joke which consists of id and joke.

id is a primary key of type String with a default value of cuid().

joke is of type String but with a constraint that it must be unique.

Open seed.js file and paste the following:

const { Photon } = require('@generated/photon')
const photon = new Photon()

async function main() {
  const joke1 = await photon.jokes.create({
    data: {
      joke:
        'Did you hear the one about the guy with the broken hearing aid? Neither did he.',
    },
  })
  const joke2 = await photon.jokes.create({
    data: {
      joke:
        'My dog used to chase people on a bike a lot. It got so bad I had to take his bike away.',
    },
  })
  const joke3 = await photon.jokes.create({
    data: {
      joke: "I don't trust stairs. They're always up to something.",
    },
  })
  const joke4 = await photon.jokes.create({
    data: {
      joke:
        "Dad died because he couldn't remember his blood type. I will never forget his last words. Be positive.",
    },
  })
  console.log({ joke1, joke2, joke3, joke4 })
}

main()
  .catch(e => console.error(e))
  .finally(async () => {
    await photon.disconnect()
  })

We are basically adding jokes into our SQLite database.

Now go inside src/index.js file and remove the contents of it. We'll start adding content from scratch.

First go ahead and import the necessary packages and declare some constants:

const { GraphQLServer } = require('graphql-yoga')
const {
  makeSchema,
  objectType,
  queryType,
  mutationType,
  idArg,
  stringArg,
} = require('nexus')
const { Photon } = require('@generated/photon')
const { nexusPrismaPlugin } = require('nexus-prisma')

We have declared a constant photon which instantiates a new Photon class.

Let us declare our Joke model. Paste the code below it:

const Joke = objectType({
  name: 'Joke',
  definition(t) {
    t.model.id()
    t.model.joke()
  },
})

We make use of objectType from the nexus package to declare Joke.

The name parameter should be the same as defined in the schema.prisma file.

The definition function lets you expose a particular set of fields wherever Joke is referenced. Here, we expose id and joke field.

If we expose only joke field, then id will not get exposed and only joke will get exposed wherever Joke is referenced.

Below that paste the Query constant:

const Query = queryType({
  definition(t) {
    t.crud.joke()
    t.crud.jokes()
  },
})

We make use of queryType from the nexus package to declare Query.

The Photon generator generates an API that exposes CRUD functions on Joke model. This is what allows us to expose t.crud.joke() and t.crud.jokes() method.

We can also write t.crud.jokes() as follows:

t.list.field('jokes', {
  type: 'Joke',
  resolve: (_, _args, ctx) => {
    return ctx.photon.jokes.findMany()
  },
})

Both the above code and t.crud.jokes() will give the same results.

In the above code, we make a field named jokes. The return type is Joke. We then call ctx.photon.jokes.findMany() to get all the jokes from our SQLite database.

Note that the name of the jokes property is auto-generated using the pluralize package. It is therefore recommended to name our models singular i.e. Joke and not Jokes.

We use the findMany method on jokes which returns a list of objects. We find all the jokes as we have mentioned no condition inside of findMany. You can learn more about how to add conditions inside of findMany here.

Below Query, paste Mutation as follows:

const Mutation = mutationType({
  definition(t) {
    t.crud.createOneJoke({ alias: 'createJoke' })
    t.crud.deleteOneJoke({ alias: 'deleteJoke' })
  },
})

Mutation uses mutationType from the nexus package.

The CRUD API here exposes createOneJoke and deleteOneJoke.

createOneJoke, as the name suggests, creates a joke whereas deleteOneJoke deletes a joke.

createOneJoke is aliased as createJoke so while calling the mutation we call createJoke rather than calling createOneJoke.

Similarly, we call deleteJoke instead of deleteOneJoke.

Finally, put the following code below Mutation:

const photon = new Photon()

new GraphQLServer({
  schema: makeSchema({
    types: [Query, Mutation, Joke],
    plugins: [nexusPrismaPlugin()],
  }),
  context: { photon },
}).start(() =>
  console.log(
    `🚀 Server ready at: http://localhost:4000\n⭐️ See sample queries: http://pris.ly/e/js/graphql#5-using-the-graphql-api`,
  ),
)

module.exports = { Joke }

We use the makeSchema method from the nexus package to combine our model Quote, add Query and Mutation to the types array. We also add nexusPrismaPlugin to our plugins array. Finally, we start our server at http://localhost:4000/. Port 4000 is the default port for graphql-yoga. You can change the port as suggested here.

Let's start the server now. But first, we need to make sure our latest schema changes are written to the node_modules/@generated/photon directory. This happens when you run prisma2 generate. After that, we need to migrate our database to create tables.

Migrate your database with Lift

Migrating your database with Lift follows a 2-step process:

Save a new migration (migrations are represented as directories on the file system)
Run the migration (to migrate the schema of the underlying database)

In CLI commands, these steps can be performed as follows (the CLI steps are in the process of being updated to match):

$ prisma2 lift save --name 'init'
$ prisma2 lift up

Now the migration process is done. We've successfully created the table. Now we can seed our database with initial values.

Go ahead and run the following command in the terminal:

$ yarn seed

This will seed our database with 8 habits as specified in our seed.js file.

Now you can run the server by typing:

$ yarn dev

This will run your server at http://localhost:4000/ which you can open and query all the APIs you've made.

List all jokes

query jokes {
  jokes {
    id
    joke
  }
}

Find A Particular Joke

query joke {
  joke(
    where: {
      joke: "Did you hear the one about the guy with the broken hearing aid? Neither did he."
    }
  ) {
    id
    joke
  }
}

Create A Joke

mutation createJoke {
  createJoke(
    data: { joke: "To the guy who invented zero... thanks for nothing." }
  ) {
    id
    joke
  }
}

Delete a joke

mutation deleteJoke {
  deleteJoke(where: { id: "ck2zqhwvo0001cav551f1me34" }) {
    id
    joke
  }
}

This is all we need for the backend. Let's work on the frontend now.

Client-Side (React Native)

Bootstrap a new Expo project

Let’s set up a new Expo project using expo-cli. Firstly, make sure to install it globally and then run the init command:

$ yarn global add expo-cli
$ expo init DadJokes

Select the following in the interactive prompts:

Select tabs
Type name of the project to be DadJokes
Press y to install dependencies with yarn

This should bootstrap a new React Native project using expo-cli.

Now run the project by typing:

$ yarn start

Press i to run the iOS Simulator. This will automatically run the iOS Simulator even if it’s not opened.

Press a to run the Android Emulator. Note that the emulator must be installed and started already before typing a. Otherwise, it will throw an error in the terminal.

It should look like this:

React Navigation

The initial setup has already installed react-navigation for us. The bottom tab navigation also works by default because we chose tabs in the second step of expo init. You can check it by tapping on Links and Settings.

The screens/ folder is responsible for the content displayed when the tabs are changed.

Now, completely remove the contents of HomeScreen.js and replace them with the following:

import React from 'react'
import { Text, View } from 'react-native'

class HomeScreen extends React.Component {
  render() {
    return (
      <View>
        <Text>Home Screen</Text>
      </View>
    )
  }
}

export default HomeScreen

Now we’ll adapt the tabs according to the application we’re going to build. For our Dad Jokes app, we’re going to have 2 screens: Home and Add Joke.

We can completely delete LinksScreen.js and SettingsScreen.js from the screens/ folder. Notice our app breaks, with a red screen full of errors.

This is because we’ve linked to it in the navigation/ folder. Open MainTabNavigator.js in the navigation/ folder. It currently looks like this:

import React from 'react';
import { Platform } from 'react-native';
import { createStackNavigator, createBottomTabNavigator } from 'react-navigation';

import TabBarIcon from '../components/TabBarIcon';
import HomeScreen from '../screens/HomeScreen';
import LinksScreen from '../screens/LinksScreen';
import SettingsScreen from '../screens/SettingsScreen';

const config = Platform.select({
  web: { headerMode: 'screen' },
  default: {},
});

const HomeStack = createStackNavigator(
  {
    Home: HomeScreen,
  },
  config
);

HomeStack.navigationOptions = {
  tabBarLabel: 'Home',
  tabBarIcon: ({ focused }) => (
    <TabBarIcon
      focused={focused}
      name={
        Platform.OS === 'ios'
          ? `ios-information-circle${focused ? '' : '-outline'}`
          : 'md-information-circle'
      }
    />
  ),
};

HomeStack.path = '';

const LinksStack = createStackNavigator(
  {
    Links: LinksScreen,
  },
  config
);

LinksStack.navigationOptions = {
  tabBarLabel: 'Links',
  tabBarIcon: ({ focused }) => (
    <TabBarIcon focused={focused} name={Platform.OS === 'ios' ? 'ios-link' : 'md-link'} />
  ),
};

LinksStack.path = '';

const SettingsStack = createStackNavigator(
  {
    Settings: SettingsScreen,
  },
  config
);

SettingsStack.navigationOptions = {
  tabBarLabel: 'Settings',
  tabBarIcon: ({ focused }) => (
    <TabBarIcon focused={focused} name={Platform.OS === 'ios' ? 'ios-options' : 'md-options'} />
  ),
};

SettingsStack.path = '';

const tabNavigator = createBottomTabNavigator({
  HomeStack,
  LinksStack,
  SettingsStack,
});

tabNavigator.path = '';

export default tabNavigator;

Remove references to LinksStack and SettingsStack completely, because we don’t need these screens in our app. It should look like this:

import React from 'react'
import { Platform } from 'react-native'
import {
  createBottomTabNavigator,
  createStackNavigator,
} from 'react-navigation'
import TabBarIcon from '../components/TabBarIcon'
import HomeScreen from '../screens/HomeScreen'

const HomeStack = createStackNavigator({
  Home: HomeScreen,
})

HomeStack.navigationOptions = {
  tabBarLabel: 'Home',
  tabBarIcon: ({ focused }) => (
    <TabBarIcon
      focused={focused}
      name={
        Platform.OS === 'ios'
          ? `ios-information-circle${focused ? '' : '-outline'}`
          : 'md-information-circle'
      }
    />
  ),
}

export default createBottomTabNavigator({
  HomeStack,
})

Now reload the app to see the error gone.

Go ahead and create AddJokeScreen.js inside the screens/ folder.

Add the following inside AddJokeScreen.js:

import React from 'react'
import { Text, View } from 'react-native'

class AddJokeScreen extends React.Component {
  render() {
    return (
      <View>
        <Text>Add Joke Screen</Text>
      </View>
    )
  }
}

export default AddJokeScreen

Open up MainTabNavigator.js and import AddJokeScreen at the top:

import AddJokeScreen from '../screens/AddJokeScreen'

Now go ahead and add the following code above our default export:

const AddJokeStack = createStackNavigator({
  AddJoke: AddJokeScreen
})

AddJokeStack.navigationOptions = {
  tabBarLabel: 'Add Joke',
  tabBarIcon: ({ focused }) => (
    <TabBarIcon
      focused={focused}
      name={
        Platform.OS === 'ios'
          ? `ios-add-circle${focused ? '' : '-outline'}`
          : 'md-add-circle'
      }
    />
  )
}

Also, change the default export to:

export default createBottomTabNavigator({
  HomeStack,
  AddJokeStack
})

Now you should see 2 screens: Home and AddJoke with their respective icons as follows:

We now need to get rid of the header that’s showing on each screen, taking up some top space. To get rid of it, we need to add headerMode: 'none' in the createStackNavigator config.

We need to add it to HomeStack and AddJokeStack.

HomeStack should become:

const HomeStack = createStackNavigator(
  { Home: HomeScreen },
  { headerMode: 'none' }
)

AddJokeStack should become:

const AddJokeStack = createStackNavigator(
  { AddJoke: AddJokeScreen },
  { headerMode: 'none' }
)

Now if you check the text goes up to the top-left right above the clock.

There’s an easy fix for this. We need to use SafeAreaView. SafeAreaView renders content within the safe area boundaries of a device. Let’s go into the screens/ directory and change HomeScreen.js to use SafeAreaView so that it looks like this:

import React from 'react'
import { SafeAreaView, Text } from 'react-native'

class HomeScreen extends React.Component {
  render() {
    return (
      <SafeAreaView>
        <Text>Home Screen</Text>
      </SafeAreaView>
    )
  }
}

export default HomeScreen

It now renders the content inside the boundaries of the device.

Also, do it for AddJokeScreen like so:

import React from 'react'
import { SafeAreaView, Text } from 'react-native'

class AddJokeScreen extends React.Component {
  render() {
    return (
      <SafeAreaView>
        <Text>Add Joke Screen</Text>
      </SafeAreaView>
    )
  }
}

export default AddJokeScreen

It’s repetitive to wrap SafeAreaView inside every component instead of setting it up on a root component like App.js. But be aware that this won’t work if you try doing it on App.js.

Remember, SafeAreaView should always be set up on screen components or any content in them, and not wrap entire navigators. You can read more about it on this blog post.

GraphQL Queries and Mutations

Lets add GraphQL queries to our app which we triggered through the GraphiQL editor.

Inside components folder, create a graphql folder.

$ mkdir graphql && cd $_

Inside graphql folder, create mutations and queries folder.

$ mkdir mutations queries

Inside queries folder, create a file named jokes.js.

$ cd queries
$ touch jokes.js

Inside jokes.js, paste the following:

import { gql } from 'apollo-boost'

export const LIST_ALL_JOKES_QUERY = gql`
  query jokes {
    jokes {
      id
      joke
    }
  }
`

Notice that the above query is similar to what we typed in the GraphiQL editor. This is how GraphQL is used. First, we type the query in the GraphiQL editor and see if it gives the data that we need and then we just copy-paste it into the application.

Inside mutations folder, create 2 files createJoke.js and deleteJoke.js.

$ cd ../mutations
$ touch createJoke.js deleteJoke.js

Inside createJoke.js, paste the following:

import { gql } from 'apollo-boost'

export const CREATE_JOKE_MUTATION = gql`
  mutation createJoke($joke: String!) {
    createJoke(data: { joke: $joke }) {
      id
      joke
    }
  }
`

Again we have copied the mutation from our GraphiQL editor above. The main difference is we have replaced the hardcoded value with a variable so we can type in whatever user has specified.

Inside deleteJoke.js, paste the following:

import { gql } from 'apollo-boost'

export const DELETE_JOKE_MUTATION = gql`
  mutation deleteJoke($id: ID) {
    deleteJoke(where: { id: $id }) {
      id
      joke
    }
  }
`

Now create 2 files in components/ folder namely Error.js and Loading.js.

$ cd ../../
$ touch Loading.js Error.js

In Error.js, paste the following:

import React from 'react'
import { StyleSheet, View } from 'react-native'
import { Text } from 'react-native-elements'

export const Error = () => (
  <View>
    <Text h3 h3Style={styles.error}>
      Sorry, looks like we've run into an error
    </Text>
  </View>
)

const styles = StyleSheet.create({
  error: {
    color: 'red'
  }
})

In Loading.js, paste the following:

import React from 'react'
import { ActivityIndicator } from 'react-native'

export const Loading = () => <ActivityIndicator size='small' />

These components will be used later in the application.

Screens

Now that our navigation is taken care of, we can start working on the layout.

We’re going to be using a UI toolkit called React Native Elements. We will also be using Apollo Client to connect to our Prisma GraphQL backend.

So go ahead and install them:

$ yarn add react-native-elements @apollo/react-hooks apollo-boost graphql

Now open up App.js and connect our client to the backend.

First, import the following:

import { ApolloProvider } from '@apollo/react-hooks'
import ApolloClient from 'apollo-boost'

Then right below it, create a constant:

const client = new ApolloClient({
  uri: 'http://localhost:4000/'
})

The uri inside of ApolloClient is pointing out to Prisma GraphQL backend.

Then in the return wrap AppNavigator with ApolloProvider and pass in the client:

<ApolloProvider client={client}>
  <AppNavigator />
</ApolloProvider>

Now anything that will be inside of AppNavigator can use Apollo Hooks.

Make sure your whole App.js file looks like:

import { ApolloProvider } from '@apollo/react-hooks'
import { Ionicons } from '@expo/vector-icons'
import ApolloClient from 'apollo-boost'
import { AppLoading } from 'expo'
import { Asset } from 'expo-asset'
import * as Font from 'expo-font'
import React, { useState } from 'react'
import { Platform, StatusBar, StyleSheet, View } from 'react-native'
import AppNavigator from './navigation/AppNavigator'

const client = new ApolloClient({
  uri: 'http://localhost:4000/'
})

export default function App(props) {
  const [isLoadingComplete, setLoadingComplete] = useState(false)

  if (!isLoadingComplete && !props.skipLoadingScreen) {
    return (
      <AppLoading
        startAsync={loadResourcesAsync}
        onError={handleLoadingError}
        onFinish={() => handleFinishLoading(setLoadingComplete)}
      />
    )
  } else {
    return (
      <View style={styles.container}>
        {Platform.OS === 'ios' && <StatusBar barStyle='default' />}
        <ApolloProvider client={client}>
          <AppNavigator />
        </ApolloProvider>
      </View>
    )
  }
}

async function loadResourcesAsync() {
  await Promise.all([
    Asset.loadAsync([
      require('./assets/images/robot-dev.png'),
      require('./assets/images/robot-prod.png')
    ]),
    Font.loadAsync({
      // This is the font that we are using for our tab bar
      ...Ionicons.font,
      // We include SpaceMono because we use it in HomeScreen.js. Feel free to
      // remove this if you are not using it in your app
      'space-mono': require('./assets/fonts/SpaceMono-Regular.ttf')
    })
  ])
}

function handleLoadingError(error) {
  // In this case, you might want to report the error to your error reporting
  // service, for example Sentry
  console.warn(error)
}

function handleFinishLoading(setLoadingComplete) {
  setLoadingComplete(true)
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff'
  }
})

Now we’ll start working on the Home screen.

Home Screen

Before starting to work on HomeScreen.js, let’s delete unnecessary files. Go to the components/ folder and delete StyledText.js and the __tests__ folder.

Open up HomeScreen.js and paste the following:

import React from 'react'
import { SafeAreaView, StyleSheet } from 'react-native'
import { Text } from 'react-native-elements'
import { ListJokes } from '../components/ListJokes'

class HomeScreen extends React.Component {
  render() {
    return (
      <SafeAreaView>
        <Text h1 h1Style={styles.h1}>
          Dad Jokes
        </Text>
        <ListJokes />
      </SafeAreaView>
    )
  }
}

const styles = StyleSheet.create({
  h1: {
    textAlign: 'center'
  }
})

export default HomeScreen

Create a new file inside the components/ folder called ListJokes.js and paste the following in it:

import { useMutation, useQuery } from '@apollo/react-hooks'
import React from 'react'
import { StyleSheet, View } from 'react-native'
import { ListItem, Text } from 'react-native-elements'
import { Error } from './Error'
import { DELETE_JOKE_MUTATION } from './graphql/mutations/deleteJoke'
import { LIST_ALL_JOKES_QUERY } from './graphql/queries/jokes'
import { Loading } from './Loading'

const removeJoke = (id, deleteJoke) => {
  deleteJoke({
    variables: {
      id
    },
    update: (cache, { data }) => {
      const { jokes } = cache.readQuery({
        query: LIST_ALL_JOKES_QUERY
      })
      cache.writeQuery({
        query: LIST_ALL_JOKES_QUERY,
        data: {
          jokes: jokes.filter(joke => joke.id !== id)
        }
      })
    }
  })
}

export const ListJokes = () => {
  const { loading, error, data } = useQuery(LIST_ALL_JOKES_QUERY)
  const [deleteJoke] = useMutation(DELETE_JOKE_MUTATION)

  if (loading) return <Loading />

  if (error) return <Error />

  const jokes = data.jokes
  return (
    <View style={styles.container}>
      {!jokes.length ? (
        <Text h4 h4Style={styles.center}>
          No jokes in the database. Add one :)
        </Text>
      ) : (
        jokes.map((item, i) => (
          <ListItem
            key={i}
            title={item.joke}
            bottomDivider
            rightIcon={{
              name: 'delete',
              onPress: () => removeJoke(item.id, deleteJoke)
            }}
          />
        ))
      )}
    </View>
  )
}

const styles = StyleSheet.create({
  container: {
    margin: 10
  },
  center: {
    textAlign: 'center',
    color: 'red'
  }
})

Here, we use the useQuery API from @apollo/react-hooks. We pass in LIST_ALL_JOKES_QUERY to it. And we get back 3 parameters, loading, error and data.

We show <Loading /> component if loading is true.

We show <Error /> component if error is true.

Then if we don't have jokes we display a friendly message No jokes in the database. Add one :).

If we do have jokes in the database then we display the jokes.

We use ListItem to render the jokes.

We specify a delete icon in the rightIcon parameter of ListItem and onPress it calls removeJoke function.

We pass in deleteJoke function to removeJoke function. This deleteJoke function we get when we call useMutation with DELETE_JOKE_MUTATION. When this function is called with an appropriate joke.id, it deletes the joke from the database.

Later, we update the cache to filter it from our local cache. This optimistically updates the UI to remove deleted results from the UI without having to refresh the app.

Add Joke Screen

Open up AddJokeScreen.js and paste the following:

import React from 'react'
import { SafeAreaView, StyleSheet } from 'react-native'
import { Text } from 'react-native-elements'
import { CreateJoke } from '../components/CreateJoke'

class HomeScreen extends React.Component {
  render() {
    return (
      <SafeAreaView>
        <Text h1 h1Style={styles.h1}>
          Add Joke
        </Text>
        <CreateJoke />
      </SafeAreaView>
    )
  }
}

const styles = StyleSheet.create({
  h1: {
    textAlign: 'center'
  }
})

export default HomeScreen

Now lets create a new file called CreateJoke.js in the components/ folder and paste the following in it:

import { useMutation } from '@apollo/react-hooks'
import React, { useState } from 'react'
import { Alert, StyleSheet, View } from 'react-native'
import { Button, Input } from 'react-native-elements'
import { Error } from './Error'
import { CREATE_JOKE_MUTATION } from './graphql/mutations/createJoke'
import { LIST_ALL_JOKES_QUERY } from './graphql/queries/jokes'

const saveJoke = (joke, changeJoke, createJoke) => {
  if (joke.trim() === '') {
    return
  }
  createJoke({
    variables: { joke },
    update: (cache, { data }) => {
      const { jokes } = cache.readQuery({
        query: LIST_ALL_JOKES_QUERY
      })

      cache.writeQuery({
        query: LIST_ALL_JOKES_QUERY,
        data: {
          jokes: jokes.concat(data.createJoke)
        }
      })
    }
  })
  Alert.alert('Joke added to the database')
  changeJoke('')
}

export const CreateJoke = () => {
  const [joke, changeJoke] = useState('')
  const [createJoke, { error, data }] = useMutation(CREATE_JOKE_MUTATION)
  if (error) {
    return <Error />
  }
  return (
    <View style={styles.wrapper}>
      <Input
        placeholder='Enter the joke'
        value={joke}
        onChangeText={changeJoke}
      />
      <Button
        type='outline'
        title='Save Joke'
        onPress={() => saveJoke(joke, changeJoke, createJoke)}
        containerStyle={styles.button}
      />
    </View>
  )
}

const styles = StyleSheet.create({
  wrapper: {
    margin: 8
  },
  button: {
    marginTop: 16,
    padding: 4
  }
})

It should look like:

Here, we simply add an Input from react-native-elements to enter the joke. Then we have Button which when submitted calls saveQuote with 3 parameters, namely, joke, changeJoke and createJoke. We get createJoke by calling in useMutation with CREATE_JOKE_MUTATION.

In saveQuote function, we call in createJoke with joke variable. This creates a joke in the database. Then we optimistically update the UI to add the new joke to the list so we don't have to refresh the app to see the results.

Later, we throw an Alert that the joke has been added and then we clear the Input by calling in changeJoke with empty string ''.

Conclusion

In this tutorial, we built a Dad Jokes app with The Prisma Framework and React Native, totally inspired by icanhazdadjoke. You can find the complete code available here on Github.

The Prisma Framework (formerly, Prisma 2) allows us to write a query in our language of choice and then it maps everything out to a database so we don't have to worry about writing it in the database language. We can easily swap out any database by using it. Right now, it only supports SQLite, mySQL, and PostgreSQL but soon other databases will be supported when it comes out of beta.

Give it a shot and I'm sure you'll like the experience.

Building Powerful GraphQL Servers with Rust

Ian Wilson — Fri, 13 Sep 2019 09:39:07 +0000

Photo by Bill Oxford on Unsplash

Setting up a GraphQL server with Rust, Juniper, Diesel, and Actix; learning about Rust's web frameworks and powerful macros along the way.

Source Code: github.com/iwilsonq/rust-graphql-example

Serving applications via GraphQL is quickly becoming the easiest and most effective way to deliver data to clients. Whether you're on a mobile device or a browser, it provides the data requested and nothing more.

Client applications no longer need to stitch together information from separate data sources. GraphQL servers are in charge of the integration, eliminating the need for excess data and round-trip requests for data.

Of course, this implies that the server has to handle aggregating data from different sources, such as home-owned backend services, databases, or third party APIs. This may be resource intensive, how can we optimize for CPU time?

Rust is a marvel of a language, pairing the raw performance of a low level language like C with the expressiveness of modern languages. It emphasizes type and memory safety, especially when there are potentially data races in concurrent operations.

Let us see what goes into building a GraphQL server with Rust. We are going to learn about

Juniper GraphQL Server
Actix web framework integrated with Juniper
Diesel for quering a SQL database
Useful Rust macros and derived traits for working with these libraries

Note that I will not go into detail regarding installing Rust or Cargo. This article assumes some preliminary knowledge of the Rust toolchain.

Setting up an HTTP Server

To begin, we need to initialize our project with cargo and then install dependencies.

    cargo new rust-graphql-example
    cd rust-graphql-example

The initialization command bootstraps our Cargo.toml file which contains our projects dependencies as well as a main.rs file which has a simple "Hello World" example.

    // main.rs

    fn main() {
      println!("Hello, world!");
    }

As a sanity check, feel free to run cargo run in order to execute the program.

Installing the necessary libraries in Rust means adding a line containing the library name and version number. Let's update the dependencies sections of Cargo.toml like so:


    # Cargo.toml

    [dependencies]
    actix-web = "1.0.0"
    diesel = { version = "1.0.0", features = ["postgres"] }
    dotenv = "0.9.0"
    env_logger = "0.6"
    futures = "0.1"
    juniper = "0.13.1"
    serde = "1.0"
    serde_derive = "1.0"
    serde_json = "1.0"

This article will cover implementing a GraphQL server using Juniper as the GraphQL library and Actix as the underlying HTTP server. Actix has a very nice API and works well with the stable version of Rust.

When those lines are added, the next time the project compiles it will include those libraries. Before we compile, lets update main.rs with a basic HTTP server, handling the index route.

    // main.rs
    use std::io;

    use actix_web::{web, App, HttpResponse, HttpServer, Responder};

    fn main() -> io::Result<()> {
        HttpServer::new(|| {
            App::new()
                .route("/", web::get().to(index))
        })
        .bind("localhost:8080")?
        .run()
    }

    fn index() -> impl Responder {
        HttpResponse::Ok().body("Hello world!")
    }

The first two lines at the top bring the module we need into scope. The main function here returns an io::Result type, which allows us to use the question mark as a shorthand for handling results.

The server's routing and configuration is created in the instance of App, which is created in a closure provided by the HTTP server's constructor.

The route itself is handled by the index function, whose name is arbitrary. As long as this function properly implements Responder it can be used as the parameter for the GET request at the index route.

If we were writing a REST API, we could proceed with adding more routes and associated handlers. We will see soon that we are trading a listing of route handlers for objects and their relations.

Now we will introduce the GraphQL library.

Creating the GraphQL Schema

At the root of every GraphQL schema is a root query. From this root we can query lists of objects, specific objects, and whatever fields they might contain.

Call this the QueryRoot, and we shall denote it with the same name in our code. Since we are not going to be setting up a database or any third party APIs, we'll be hard-coding the little data we have here.

To add a little color to this example, the schema will depict a generic list of members.

Under src, add a new file called graphql_schema.rs along with the following contents:

    // graphql_schema.rs
    use juniper::{EmptyMutation, RootNode};

    struct Member {
      id: i32,
      name: String,
    }

    #[juniper::object(description = "A member of a team")]
    impl Member {
      pub fn id(&self) -> i32 {
        self.id  
      }

      pub fn name(&self) -> &str {
        self.name.as_str()
      }
    }

    pub struct QueryRoot;

    #[juniper::object]
    impl QueryRoot {
      fn members() -> Vec<Member> {
        vec![
          Member {
            id: 1,
            name: "Link".to_owned(),
          },
          Member {
            id: 2,
            name: "Mario".to_owned(),
          }
        ]
      }
    }

Along with our imports, we define our first GraphQL object in this project, the member. They are simple beings, with an id and name. We'll think about more complicated fields and patterns later.

After stubbing out the QueryRoot type as a unit struct, we get to define the field itself. Juniper exposes a Rust macro called object which allows us to define fields on the different nodes throughout our schema. For now, we only have the QueryRoot node, so we'll expose a field called members on it.

Rust macros often have an unusual syntax compared to standard functions. They don't merely take some arguments and produce a result, they expand into much more complex code at compile time.

Exposing the Schema

Below our macro call to create the members field, we will define the RootNode type that we expose on our schema.

    // graphql_schema.rs

    pub type Schema = RootNode<'static, QueryRoot, EmptyMutation<()>>;

    pub fn create_schema() -> Schema {
      Schema::new(QueryRoot {}, EmptyMutation::new())
    }

Because of the strong typing in Rust, we are forced to provide the mutation object argument. Juniper exposes an EmptyMutation struct for just this occasion, that is, when we want to create a read-only schema.

Now that the schema is prepared, we can update our server in main.rs to handle the "/graphql" route. Since having a playground is also nice, we'll add a route for GraphiQL, the interactive GraphQL playground.

    // main.rs
    #[macro_use]
    extern crate juniper;

    use std::io;
    use std::sync::Arc;

    use actix_web::{web, App, Error, HttpResponse, HttpServer};
    use futures::future::Future;
    use juniper::http::graphiql::graphiql_source;
    use juniper::http::GraphQLRequest;

    mod graphql_schema;

    use crate::graphql_schema::{create_schema, Schema};

    fn main() -> io::Result<()> {
        let schema = std::sync::Arc::new(create_schema());
        HttpServer::new(move || {
            App::new()
                .data(schema.clone())
                .service(web::resource("/graphql").route(web::post().to_async(graphql)))
                .service(web::resource("/graphiql").route(web::get().to(graphiql)))
        })
        .bind("localhost:8080")?
        .run()
    }

You'll notice I've specified a number of imports that we will be using, including the schema we've just created. Also see that:

we call create_schema inside an Arc (atomically reference counted), to allow shared immutable state across threads (cooking with 🔥 here I know)
we mark the closure inside HttpServer::new with move, indicating that the closure takes ownership of the inner variables, that is, it gains a copy of schema
schema is passed to the data method indicating that it is to be used inside the application as shared state between the two services

We must now implement the handlers for those two services. Starting with the "/graphql" route:

    // main.rs

    // fn main() ...

    fn graphql(
        st: web::Data<Arc<Schema>>,
        data: web::Json<GraphQLRequest>,
    ) -> impl Future<Item = HttpResponse, Error = Error> {
        web::block(move || {
            let res = data.execute(&st, &());
            Ok::<_, serde_json::error::Error>(serde_json::to_string(&res)?)
        })
        .map_err(Error::from)
        .and_then(|user| {
            Ok(HttpResponse::Ok()
                .content_type("application/json")
                .body(user))
        })
    }

Our implementation of the "/graphql" route takes executes a GraphQL request against our schema from application state. It does this by creating a future from web::block and chaining handlers for success and error states.

Futures are analogous to Promises in JavaScript, which is enough to understand this code snippet. For a greater explanation of Futures in Rust, I recommend this article by Joe Jackson.

In order to test out our GraphQL schema, we'll also add a handler for "/graphiql".

    // main.rs

    // fn graphql() ...

    fn graphiql() -> HttpResponse {
        let html = graphiql_source("http://localhost:8080/graphql");
        HttpResponse::Ok()
            .content_type("text/html; charset=utf-8")
            .body(html)
    }

This handler is much simpler, it merely returns the html of the GraphiQL interactive playground. We only need to specify which path is serving our GraphQL schema, which is "/graphql" in this case.

With cargo run and navigation to http://localhost:8080/graphiql, we can try out the field we configured.

It does seem to take a little more effort than setting up a GraphQL server with Node.js and Apollo but the static typing of Rust combined with its incredible performance makes it a worthy trade — if you're willing to work at it.

Setting up Postgres for Real Data

If I stopped here, I wouldn't even be doing the examples in the docs much justice. A static list of two members that I wrote myself at dev time will not fly in this publication.

Installing Postgres and setting up your own database belongs in a different article, but I'll walk through how to install diesel, the popular Rust library for handling SQL databases.

See here to install Postgres locally on your machine. You can also use a different database like MySQL in case you are more familiar with it.

The diesel CLI will walk us through initializing our tables. Let's install it:

    cargo install diesel_cli --no-default-features --features postgres

After that, we will add a connection URL to a .env file in our working directory:

    echo DATABASE_URL=postgres://localhost/rust_graphql_example > .env

Once that's there, you can run:

    diesel setup

    # followed by

    diesel migration generate create_members

Now you'll have a migrations folder in your directory. Within it, you'll have two SQL files: one up.sql for setting up your database, the other down.sql for tearing it down.

I will add the following to up.sql:

    CREATE TABLE teams (
      id SERIAL PRIMARY KEY,
      name VARCHAR NOT NULL
    );

    CREATE TABLE members (
      id SERIAL PRIMARY KEY,
      name VARCHAR NOT NULL,
      knockouts INT NOT NULL DEFAULT 0,
      team_id INT NOT NULL,
      FOREIGN KEY (team_id) REFERENCES teams(id)
    );

    INSERT INTO teams(id, name) VALUES (1, 'Heroes');
    INSERT INTO members(name, knockouts, team_id) VALUES ('Link', 14, 1);
    INSERT INTO members(name, knockouts, team_id) VALUES ('Mario', 11, 1);
    INSERT INTO members(name, knockouts, team_id) VALUES ('Kirby', 8, 1);

    INSERT INTO teams(id, name) VALUES (2, 'Villains');
    INSERT INTO members(name, knockouts, team_id) VALUES ('Ganondorf', 8, 2);
    INSERT INTO members(name, knockouts, team_id) VALUES ('Bowser', 11, 2);
    INSERT INTO members(name, knockouts, team_id) VALUES ('Mewtwo', 12, 2);

And into down.sql I will add:

    DROP TABLE members;
    DROP TABLE teams;

If you've written SQL in the past, these statements will make some sense. We are creating two tables, one to store teams and one to store members of those teams.

I am modeling this data based on Smash Bros if you have not yet noticed. It helps the learning stick.

Now to run the migrations:

    diesel migration run

If you'd like to verify that the down.sql script works to destroy those tables, run: diesel migration redo.

Now the reason why I named the GraphQL schema file graphql_schema.rs instead of schema.rs, is because diesel overwrites that file in our src direction by default.

It keeps a Rust macro representation of our SQL tables in that file. It is not so important to know how exactly this table! macro works, but try not to edit this file — the ordering of the fields matters!

    // schema.rs (Generated by diesel cli)

    table! {
        members (id) {
            id -> Int4,
            name -> Varchar,
            knockouts -> Int4,
            team_id -> Int4,
        }
    }

    table! {
        teams (id) {
            id -> Int4,
            name -> Varchar,
        }
    }

    joinable!(members -> teams (team_id));

    allow_tables_to_appear_in_same_query!(
        members,
        teams,
    );

Finally, thanks to a comment, we'll want to import diesel and expose the schema module in main.rs:


    #[macro_use]
+   extern crate diesel;
    extern crate juniper;

    use std::io;
    use std::sync::Arc;

    use actix_web::{web, App, Error, HttpResponse, HttpServer};
    use futures::future::Future;
    use juniper::http::graphiql::graphiql_source;
    use juniper::http::GraphQLRequest;

    mod graphql_schema;
+   mod schema;

    use crate::graphql_schema::{create_schema, Schema};

Wiring up our Handlers with Diesel

In order to serve the data in our tables, we must first update our Member struct with the new fields:

// graphql_schema.rs

+ #[derive(Queryable)]
pub struct Member {
  pub id: i32,
  pub name: String,
+ pub knockouts: i32,
+ pub team_id: i32,
}

#[juniper::object(description = "A member of a team")]
impl Member {
  pub fn id(&self) -> i32 {
    self.id  
  }

  pub fn name(&self) -> &str {
    self.name.as_str()
  }

+ pub fn knockouts(&self) -> i32 {
+   self.knockouts
+ }

+ pub fn team_id(&self) -> i32 {
+   self.team_id
+ }
}

Note that we are also adding the Queryable derived attribute to Member. This tells Diesel everything it needs to know in order to query the right table in Postgres.

Additionally, add a Team struct:

    // graphql_schema.rs

    #[derive(Queryable)]
    pub struct Team {
      pub id: i32,
      pub name: String,
    }

    #[juniper::object(description = "A team of members")]
    impl Team {
      pub fn id(&self) -> i32 {
        self.id
      }

      pub fn name(&self) -> &str {
        self.name.as_str()
      }

      pub fn members(&self) -> Vec<Member> {
        vec![]
      }
    }

In a short while, we will update the members function on Team to return a database query. But first, let us add a root call for members.

    // graphql_schema.rs
    + extern crate dotenv;

    + use std::env;

    + use diesel::pg::PgConnection;
    + use diesel::prelude::*;
    + use dotenv::dotenv;
    use juniper::{EmptyMutation, RootNode};

    + use crate::schema::members;

    pub struct QueryRoot;

    +  fn establish_connection() -> PgConnection {
    +    dotenv().ok();
    +    let database_url = env::var("DATABASE_URL").expect("DATABASE_URL must be set");
    +    PgConnection::establish(&database_url).expect(&format!("Error connecting to {}", database_url))
    +  }

    #[juniper::object]
    impl QueryRoot {
      fn members() -> Vec<Member> {
    -   vec![
    -     Member {
    -       id: 1,
    -       name: "Link".to_owned(),
    -     },
    -     Member {
    -       id: 2,
    -       name: "Mario".to_owned(),
    -     }
    -   ]
    +   use crate::schema::members::dsl::*;
    +   let connection = establish_connection();
    +   members
    +     .limit(100)
    +     .load::<Member>(&connection)
    +     .expect("Error loading members")
      }
    }

Very good, we have our first usage of a diesel query. After initializing a connection, we use the members dsl, which is generated from our table! macros in schema.rs, and call load, indicating that we wish to load Member objects.

Establishing a connection means connecting to our local Postgres database by using the env variable we declared earlier.

Assuming that was all input correctly, restart the server with cargo run, open GraphiQL and issue the members query, perhaps adding the two new fields.

The teams query will be very similar — the difference being we must also add a part of the query to the members function on the Team struct in order to resolve the relationship between GraphQL types.

    // graphql_schema.rs

    #[juniper::object]
    impl QueryRoot {
      fn members() -> Vec<Member> {
        use crate::schema::members::dsl::*;
        let connection = establish_connection();
        members
          .limit(100)
          .load::<Member>(&connection)
          .expect("Error loading members")
      }

    +  fn teams() -> Vec<Team> {
    +    use crate::schema::teams::dsl::*;
    +    let connection = establish_connection();
    +    teams
    +      .limit(10)
    +      .load::<Team>(&connection)
    +      .expect("Error loading teams")
    +  }
    }

    // ...

    #[juniper::object(description = "A team of members")]
    impl Team {
      pub fn id(&self) -> i32 {
        self.id
      }

      pub fn name(&self) -> &str {
        self.name.as_str()
      }

      pub fn members(&self) -> Vec<Member> {
    -    vec![]
    +    use crate::schema::members::dsl::*;
    +    let connection = establish_connection();
    +    members
    +      .filter(team_id.eq(self.id))
    +      .limit(100)
    +      .load::<Member>(&connection)
    +      .expect("Error loading members")
      }
    }

When running this is GraphiQL, we get:

I really like the way this is turning out, but there is one more thing we must add in order to call this tutorial complete.

The Create Member Mutation

What good is a server if it is read-only and not writable? Well I'm sure those have their uses too, but we would like to write data to our database, how hard can it be?

First we'll create a MutationRoot struct that will eventually replace our usage of EmptyMutation. Then we will add the diesel insertion query.

    // graphql_schema.rs

    // ...

    pub struct MutationRoot;

    #[juniper::object]
    impl MutationRoot {
      fn create_member(data: NewMember) -> Member {
        let connection = establish_connection();
        diesel::insert_into(members::table)
          .values(&data)
          .get_result(&connection)
          .expect("Error saving new post")
      }
    }

    #[derive(juniper::GraphQLInputObject, Insertable)]
    #[table_name = "members"]
    pub struct NewMember {
      pub name: String,
      pub knockouts: i32,
      pub team_id: i32,
    }

As GraphQL mutations typically go, we define an input object called NewMember and make it the argument of the create_member function. Inside this function, we establish a connection and call the insert query on the members table, passing the entire input object.

It is super convenient that Rust allows us to use the same structs for GraphQL input objects as well as Diesel insertable objects.

Let me make this a little more clear, for the NewMember struct:

we derive juniper::GraphQLInputObject in order to create a input object for our GraphQL schema
we derive Insertable in order to let Diesel know that this struct is valid input for an insertion SQL statement
we add the table_name attribute so that Diesel knows which table to insert it in

There is a lot of magic going on here. This is what I love about Rust, it has great performance but the code has features like macros and derived traits to abstract away boilerplate and add functionality.

Finally, at the bottom of the file, add the MutationRoot to the schema:

    // graphql_schema.rs

    pub type Schema = RootNode<'static, QueryRoot, MutationRoot>;

    pub fn create_schema() -> Schema {
      Schema::new(QueryRoot {}, MutationRoot {})
    }

I hope that everything is there, we can test out all of our queries and mutations thus far now:

    # GraphiQL

    mutation CreateMemberMutation($data: NewMember!) {
      createMember(data: $data) {
        id
        name
        knockouts
        teamId
      }
    }

    # example query variables
    # {
    #   "data": {
    #     "name": "Samus",
    #     "knockouts": 19,
    #     "teamId": 1
    #   }
    # }

If that mutation ran successfully, you can pop open a bottle of champagne as you are on your way to building performant and type-safe GraphQL Servers with Rust.

Thanks For Reading

I hope you have enjoyed this article, I also hope that it gave you some sort of inspiration for your own work.

If you'd like to keep up with the next time I drop an article in the realm of Rust, ReasonML, GraphQL, or software development at large, feel free to give me a follow on Twitter, dev.to, or on my website at ianwilson.io.

The source code is here github.com/iwilsonq/rust-graphql-example.

GraphQL and Urql by Example

Akshay Kadam (A2K) — Tue, 27 Aug 2019 07:49:26 +0000

According to the docs,

urql is a GraphQL client that exposes a set of React components and hooks. It's built to be highly customisable and versatile so you can take it from getting started with your first GraphQL project all the way to building complex apps and experimenting with GraphQL clients.

Urql, pronounced as Urkel, recently reached v1.0 a few months ago. Unlike Apollo, it is a minimalistic GraphQL Client. Urql was introduced as a response to Apollo's growing complexity of setup.

Comparison between Apollo and Urql

A detailed comparison between Apollo and Urql can be found below (credits to this original gist, edited for recent corrections):

Features	Apollo Client	Urql
Cache	Normalized objects	Hashing query + variables. Normalized Cache is WIP
Batching	With `apollo-link-batch-http` (although it recommends deferring batching as long as possible)	Doesn't have a first-party solution but allows to use Apollo's Link extensions
Deduping	With `apollo-link-dedup` (enabled by default)	With `dedupExchange`
Authentication	Supports adding options to the `fetch` client or changing the network layer altogether	Supports adding options to the `fetch` client or changing the network layer altogether
Pagination	First-party support with fetchMore, also provides several recipes	No first-party support, needs to implement a custom solution
React Hooks	Officially supported as of v3.0	First-party support
Optimistic update	`mutate({ optimisticResponse })` (requires manipulating the cache if inserting new data)	No support because of document based cache
Local state	Support with `@client` directive	No official support
Refetch after mutation	`mutate({ refetchQueries })`	Needs to manually call a function obtained when performing the query
Subscriptions	Supported	Supported
Community	Vibrant, easy to find answers online, official chat, huge number of issues and PRs	Almost non-existent
Documentation	Very thorough, with several tutorials and recipes	Comprehensive

Setting up the GraphQL server

A GraphQL server has been made with Prisma 2 specifically for the purpose of this tutorial so make sure you clone it.

After cloning it, install the dependencies using yarn. This will also run the postinstall hook which runs prisma2 generate that generates the photon and nexus-prisma types inside node_modules/@generated folder.

Go ahead and start the server using:

$ yarn start

Open up http://localhost:4000 to play around with the GraphQL API.

Getting Started with Urql

Install urql with the package manager of your choice:

$ yarn add urql
# or
$ npm install urql

urql has a Provider component similar to other libraries like react-redux which manages state and data. You need to wrap your app with the Provider component. This <Provider> component holds the client that is used to manage data, requests, the cache, and other things such that every component below it has an access to the client and it can query or mutate the data.

import React from 'react';
import { Provider, createClient } from 'urql';

const client = createClient({
  url: "http://localhost:4000"
});

const App = () => (
    <Provider value={client}>
    {/* ... */}
    </Provider>
);

export default App;

Querying data in Urql using Render Props or React Hooks

Let us query some GraphQL data using urql's Query component.

import React from 'react';
import { useQuery } from "urql";

const getPokemonData = `
    query GetPokemonData($name: String!) {
        pokemon(name: $name) {
            id
            number
            name
            attacks {
                special {
                    id
                    name
                    damage
                }
            }
        }
    }
`;

export const ListPokemonDataQuery = ({ name = "Pikachu" }) => {
    const [{ fetching, data, error }] = useQuery({
        query: getPokemonData,
        variables: { name }
    });

    if (fetching) {
        return `Loading ${name}...`;
    } else if (error) {
        return `Oh no! Error: ${error}`;
    }

    const pokemon = data.pokemon[0];
    return (
        <>
            <h1>
                #{pokemon.number} {pokemon.name}
            </h1>
            <ul>
                {pokemon.attacks.special.map(({ name, id, damage }) => (
                    <li key={name}>
                        #{id} {name} - {damage}
                    </li>
                ))}
            </ul>
        </>
    );
};

The above Query component sends getPokemonData query with name as a variable to the GraphQL API mentioned in url property of createClient.

Query is a render prop which is nothing but a React component whose value is a function. This render prop gives us fetching, data and error. fetching returns a boolean whether the request is still being sent and is still loading. data gives us the data returned by the GraphQL API and error gives us whether we have any errors with the GraphQL API.

urql also has a first-class Hooks support so we can also use useQuery function.

If we rewrite the above example, it would look like:

import React from "react";
import { useQuery } from "urql";

const getPokemonData = `
    query GetPokemonData($name: String!) {
        pokemon(name: $name) {
            id
            number
            name
            attacks {
                special {
                    id
                    name
                    damage
                }
            }
        }
    }
`;

export const ListPokemonDataHook = ({ name = "Pikachu" }) => {
    const [{ fetching, data, error }] = useQuery({
        query: getPokemonData,
        variables: { name },
    })

    if (fetching) {
        return `Loading ${name}...`;
    } else if (error) {
        return `Oh no! Error: ${error}`;
    }

    const pokemon = data.pokemon[0];
    return (
        <>
            <h1>
                #{pokemon.number} {pokemon.name}
            </h1>
            <ul>
                {pokemon.attacks.special.map(({ name, id, damage }) => (
                    <li key={name}>
                        #{id} {name} - {damage}
                    </li>
                ))}
            </ul>
        </>
    );
}

Notice, how the useQuery hook simplifies the component structure. useQuery works like any other React Hook as it takes in a value and returns a tuple. The value it takes in is a query and a variable name and it returns back a tuple containing fetching, data and error. Everything else is just the same.

Mutating data in Urql using Render Props or React Hooks

Let us mutate some GraphQL data using urql's Mutation component.

import React, { useState } from 'react';
import { Mutation } from 'urql';

const addPokemon = `
  mutation AddPokemon($number: Int!, $name: String!) {
    addPokemon(data: {
      number: $number,
      name: $name
    }) {
      id
      number
      name
    }
  }
`

export const InsertPokemonMutation = () => {
  const [name, setName] = useState('')
  return (
    <Mutation query={addPokemon}>
      {({ fetching, data, error, executeMutation }) => {
        return (
          <>
            {error && <div>Error: {JSON.stringify(error)}</div>}
            <input value={name} onChange={e => setName(e.target.value)} />
            <button onClick={() => {
              if (name.trim() === "") return // return if input is empty
              executeMutation({ name, number: Math.ceil(Math.random() * 1000) })
              setName("") // clear the input
            }}>
              Add Pokemon
            </button>
            {data && (<div>
              <br/>
              Mutation successful: 
              <pre>{JSON.stringify(data, null, 2)}</pre>
            </div>)}
          </>
        )
      }}
    </Mutation>
  )
}

Mutation component takes in a query and returns executeMutation. executeMutation is a function which takes in a variable name and a random number as stated in our addPokemon query above and calls the Mutation. If the mutation is unsuccessful then an error is displayed. The render prop also gives you fetching and data if you want to do anything with it.

If we rewrite the above example using useMutation hook then it would look like:

import React, { useState } from 'react';
import { useMutation } from 'urql';

const addPokemon = `
  mutation AddPokemon($number: Int!, $name: String!) {
    addPokemon(data: {
      number: $number,
      name: $name
    }) {
      id
      number
      name
    }
  }
`

export const InsertPokemonHook = () => {
  const [name, setName] = useState('')
  const [{ fetching, data, error }, executeMutation] = useMutation(addPokemon)
  return (
    <>
      {error && <div>Error: {JSON.stringify(error)}</div>}
      <input value={name} onChange={e => setName(e.target.value)} />
      <button onClick={() => {
        if (name.trim() === "") return
        executeMutation({ name, number: Math.ceil(Math.random() * 1000) })
        setName("")
      }}>
        Add Pokemon
      </button>
      {data && (<div>
        <br/>
        Mutation successful: 
        <pre>{JSON.stringify(data, null, 2)}</pre>
      </div>)}
    </>
  )
}

useMutation takes in the mutation addPokemon and returns the mutations state (fetching, data and error) and executeMutation function in a tuple. executeMutation is then called on a click of the button.

What are Exchanges in Urql

urql has a concept of exchanges. When a new Client() is created you pass it a url and fetchOptions. But you can also pass it an exchanges array. Exchanges are operation handlers. It receives client and forward function as an object and returns a function accepting a stream of operations and returning a stream of operation results (i.e. GraphQL results).

In other words, exchanges are handlers that fulfill our GraphQL requests. They're Input/Output streams, inputs being operations, outputs being results.

By default, urql creates 3 different exchanges namely dedupExchange, cacheExchange and fetchExchange.

dedupExchange deduplicates pending operations. It eliminates duplicate operations waiting for a response as it wouldn't make sense to send the same operation twice at the same time.

cacheExchange checks operations against the cache. Depending on the requestPolicy cached results can be resolved instead and results from network requests are cached.

fetchExchange sends an operation to the API and returns results.

When a new Client() is created and no exchanges are passed to it then some are added automatically, which is the same as creating a new Client() using the following exchanges:

import { Client, dedupExchange, cacheExchange, fetchExchange } from "urql";

const client = new Client({
  url: "http://localhost:4000",
  exchanges: [dedupExchange, cacheExchange, fetchExchange]
});

This can also be written as:

import { Client, defaultExchanges } from "urql";

const client = new Client({
  url: "http://localhost:4000",
  exchanges: defaultExchanges
});

Now that we know what are exchanges, lets learn about subscriptions.

Subscribing to data in Urql using Render Props or React Hooks

Go ahead and first install subscriptions-transport-ws using yarn:

$ yarn add subscriptions-transport-ws

To use subscriptions, we need to first add subscriptionExchange to our new Client() and also create a new SubscriptionClient() using websocket protocol as follows:

import { SubscriptionClient } from "subscriptions-transport-ws";
import { Client, defaultExchanges, subscriptionExchange } from "urql";

const subscriptionClient = new SubscriptionClient(
  "ws://localhost:4001/graphql",
  {
    reconnect: true,
    timeout: 20000
  }
);

const client = new Client({
  url: "http://localhost:4000",
  exchanges: [
    ...defaultExchanges,
    subscriptionExchange({
      forwardSubscription: operation => subscriptionClient.request(operation)
    })
  ]
});

Now we can start using Subscription component in our App:

import React from 'react'
import { Subscription } from 'urql'

const newPokemon = `
  subscription PokemonSub {
    newPokemon {
      id
      number
      name
      attacks {
        special {
          name
          type
          damage
        }
      }
    }
  }
`

const NewPokemon = () => (
  <Subscription query={newPokemon}>
    {({ fetching, data, error }) => {
      if (fetching) {
        return `Loading...`
      } else if (error) {
        return `Oh no! Error: ${error}`
      }

      const { newPokemon } = data
      return (
        <>
          <h1>
            #{newPokemon.number} {newPokemon.name}
          </h1>
          <ul>
            {newPokemon.attacks.special.map(({ name, type, damage }) => (
              <li key={name}>
                {name} ({type}) - {damage}
              </li>
            ))}
          </ul>
        </>
      )
    }}
  </Subscription>
)

Subscription component works in similar way to the Query component. It can take in a query and a variables prop. It also has fetching, data and error just like a Query component. The data and error of the render props will change every time a new event is received by the server.

We can also use useSubscription hook as follows:

import React from 'react';
import { useSubscription } from 'urql';

const newPokemon = `
  subscription PokemonSub {
    newPokemon {
      id
            number
            name
            attacks {
                special {
                    name
                    type
                    damage
                }
            }
    }
  }
`

export const NewPokemonSubscriptionHook = () => {
  const [{ fetching, data, error }] = useSubscription({ query: newPokemon }, (pokemons = [], res) => {
        return [res.newPokemon, ...pokemons] 
    })

  if (fetching) {
    return `Loading...`
  } else if (error) {
    return `Oh no! Error: ${error}`
  }
    return (
        <>
            {data.map(pokemon => {
              const { newPokemon } = pokemon
                return (
                    <div key={newPokemon.number}>
                        <h1>
                            #{newPokemon.number} {newPokemon.name}
                        </h1>
                        <ul>
                            {newPokemon.attacks.special.map(({ name, type, damage }) => (
                                <li key={name}>
                                    {name} ({type}) - {damage}
                                </li>
                            ))}
                        </ul>
                    </div>
                )
            })}
        </>
    )
}

useSubscription takes in the subscription newPokemon and returns the subscriptions state (fetching, data and error). Additionally, the second argument for useSubscription can be an optional reducer function which works like Array.prototype.reduce. It receives the previous set of data that this function has returned or undefined. As the second argument, it receives the event that has come in from the subscription. You can use this to accumulate the data over time, which is useful for a list for example.

Conclusion

In this tutorial, we learnt about URQL (Universal React Query Library) which is a blazing-fast GraphQL client, exposed as a set of ReactJS components. We then laid out the differences between Apollo and Urql.

We learnt about the Query API, Mutation API and Subscription API provided by Urql. We also used the hooks useQuery, useMutation and useSubscription to reduce the callback hell boilerplate unnecessarily created by Render Props.

We also learnt about Exchanges. Finally, we created a simple Pokemon application using Urql. Urql is a new piece of technology but it is mature enough to be used in production. Although, some things like Optimistic Updates do not yet work due to lack of cache normalization but its a work-in-progress and soon will be released.

Multiple Apollo Clients in React

Rafael Nunes — Fri, 09 Aug 2019 01:22:15 +0000

This is a review after one year of Apollo Multiple Clients with React?. I took a time to rewrite it, adding community implementation suggestions, Apollo Federation, etc. Realised then that I could share my humble knowledge here as well.

This quick post explains how to use different Apollo clients in the same React application, but in the end, discuss other approaches when working on multiple GraphQL APIs. This is not intended to question the GraphQL philosophy by any means 😝!

I wrote this because I found myself questioning how could I use multiple clients to query different GraphQL APIs from my React application. It turns out there were lots of issues in Apollo GitHub project, discussing the need and presenting suggested implementations for it.

TL;DR: passing any ApolloClient instance to Query/Mutation/Subscription components as props works just fine! Check: https://github.com/peaonunes/apollo-multiple-clients-example

Some links to related issues, discussions, and proposals are listed below. Some of the old proposals indeed were merged and come along old react-apollo versions. However, the approach to using the Apollo client and querying changed a lot (for better) since 2.1.

Why would we need multiple Apollo clients?

Apollo Client accepts only one client uri on its initialization, therefore, it is meant to be used with one client at the time.

import ApolloClient from "apollo-boost";

const client = new ApolloClient({
 uri: "https://48p1r2roz4.sse.codesandbox.io"
});

So if in your React application you need to retrieve data from two different GraphQL services, for example, you cannot use the same client or provider instance.

In my case specifically, I was just looking for a quick win implementation approach to get data from two GraphQL APIs to validate a solution. I was not worrying too much about schemas collision since the types, cache, state (...) would not overlap.

In my scenario, it would make sense to have a way of switching clients when querying APIs on Apollo. In the current approach though, you wrap your entire application with the ApolloProvider component which passes the client for the application through the context.

import { ApolloProvider } from "react-apollo";
import ApolloClient from "apollo-boost";
import { render } from "react-dom";
import React from "react";

const client = new ApolloClient({
 uri: "https://48p1r2roz4.sse.codesandbox.io"
});

const App = () => (
 <ApolloProvider client={client}>
 <div>
 <h2>My first Apollo app 🚀</h2>
 </div>
 </ApolloProvider>
);

render(<App />, document.getElementById("root"));

That actually makes it simple to query data using the Query Component, but it also means that the client provided via context is the only used when querying.

⭐️ First Solution

I spent some time looking through numerous issues and related projects and it turns out that there is a way of overriding the context client for Query and Mutation component passing another client through props 🎉 🎉 !

Update Aug 2019: Although they have changed the implementation it still works. https://github.com/apollographql/react-apollo/blob/master/packages/components/src/Query.tsx#L17

 <Query client={anotherClient} query={query}>
 {({ data }) => (<div>{data.name}</div>)}
 </Query>

This feature is not mentioned in any part of the official documentation. We can indeed pass any client for the components that they will give preference for the one passed via props order than via context. So we could make:

// ...
const customClient = new ApolloClient({
  uri: "http://other-api/graphql"
});

const Dogs = ({ onDogSelected }) => (
  <Query query={GET_DOGS} client={customClient} >
    {({ loading, error, data }) => {
      if (loading) return "Loading...";
      if (error) return `Error! ${error.message}`;

      return (
        <select name="dog" onChange={onDogSelected}>
          {data.dogs.map(dog => (
            <option key={dog.id} value={dog.breed}>
              {dog.breed}
            </option>
          ))}
        </select>
      );
    }}
  </Query>
);
// ...

I have implemented a runnable example that uses two different clients in this repository: https://github.com/peaonunes/apollo-multiple-clients-example

Even though this approach is functional you should keep in mind that you won't have Apollo features running applying for both clients unless you pass the same cache to the clients (that might be a risk in case of schema collision), manage other features will be by your own. Apollo features will get compromised and as the application grows your codebase becomes thicker and development will probably be slower.

What would be the ideal approach then?

Solving the problem in the Frontend

Some people found the original article on medium and beyond discussing the approaches they have come up with their implementations for solving this issue.

Community implementations

Michael Duve, wrote react-apollo-multiple-clients a packaged that allows you to switch between clients. It considers multiple providers and provides you a HOC component that accepts a client prop to switch to the desired client consumer. Discussion

Paul Grieselhuber, suggested in his post a way where everything worked through a single client and allowed you to simply toggle on context to select a uri where the client will dispatch the requests. You can follow the discussion here.

Client-side schema stitching

Despite support for server side, it is not common to see people trying to solve the issue right on the client, there are some issues looking for or requesting stitching on client side, #797 for example.

The company Hasura, though, points out a way of client side schema stitching and it might be sufficient in your case.

Although I think that these approaches solve the problem I also think they can increase so much the complexity of the frontend application as the application grows. From my point of view, the work should be done on Backend by providing a unique interface for all the different APIs.

Gateways for Frontends

API Gateway is a known pattern with increasing adoption in our "microservice boom" age. API Gateway is a single interface between the services and clients.

It seems to be a consensus in the GraphQL world as well that the API Gateway is the way to go on connection with different GraphQL APIs. However sometimes going beyond that, since the Gateway itself can create a GraphQL interface for other REST and RPC APIs.

The real problem of serving different APIs through a unique gateway is how to manage and orchestrate different schemas.

Schema Stitching

The first attempt the Apollo team advocated for was Schema Stitching.

Schema stitching is the process of creating a single GraphQL schema from multiple underlying GraphQL APIs.

After some time of development and feedback from the community this approach was considered fragile and it is now deprecated.

Apollo Federation

Apollo recently launched a new concept for solving this problem of managing different schemas through a gateway which is called Apollo Federation.

"Apollo Federation is our answer for implementing GraphQL in a microservice architecture. It’s designed to replace schema stitching and solve pain points such as coordination, separation of concerns, and brittle gateway code." James Baxley III

They have launched the Federation spec before and it already counts with implementations in some languages, apollo-gateway, for example. The idea is to have a gateway that composes the schemas and the federated services can connect with each other through keys (just like primary keys) and they are also able to extend types. All this just using regular GraphQL spec.

I recommend taking the time to watch the video below and spend some time playing around with this promising approach.

Apollo Federation - A revolutionary architecture for building a distributed graph

I personally tried it and I am seeing companies working on solutions based on this new approach. It is also notable that there are some challenges and space for other discussions like managing authentication/authorization, how flexible the gateway should be, etc. Hopefully, the Federation get evolving based on feedbacks from the community and companies.

Conclusion

As I mentioned before this post is not about questioning the right way on querying multiple GraphQL APIs, but it is about pointing out approaches that hopefully might be enough for solving the issues of today.

I think the whole discussion about using API Gateways and managing different GraphQL schemas is just at the beginning and the community will continuously work on better solutions.

I am more than happy to read suggestions and engage discussions so leave your thoughts below.

GraphQL Recipes (V2) - Building APIs with GraphQL Transform

Nader Dabit — Thu, 08 Aug 2019 13:58:18 +0000

This is V2 of this post, updated with new schemas and the most up to date directives from Amplify.

Cover photo by Tarn Nguyen on Unsplash

To view the repo only containing the code and instructions for deploying these applications, click here.

In my post Infrastructure as Code in the Era of GraphQL and Full Stack Serverless I showed how you could leverage GraphQL, the AWS Amplify CLI, and the GraphQL Transform library to build, share, and deploy full stack cloud applications.

In this post I've created annotated GraphQL schemas that you can use to deploy popular types of applications.

The GraphQL Transform library allows you to deploy AWS AppSync GraphQL APIs with features like NoSQL databases, authentication, elasticsearch engines, lambda function resolvers, relationships, authorization, and more using GraphQL schema directives.

For example, take the following schema that is utilizing the @model directive:

type Note @model {
  id: ID!
  name: String!
  description: String
}

This schema will deploy the following:

GraphQL API
CRUD GraphQL operations for this base type: Create, Read, Update, Delete, and List
GraphQL subscriptions (triggered by mutation events; create, update, delete)
DynamoDB NoSQL Database
GraphQL resolvers mapping the DynamoDB table to the GraphQL CRUD operations

As of this post there are 8 directives offered by the GraphQL Transform library:

@model
// Deploys DynamodDB table + resolvers + additional GraphQL schema

@auth
// Allows the definition of auth rules and builds corresponding GraphQL resolvers based on these rules

@connection
// Enables you to specify relationships between `@model` object types 

@searchable
// Handles streaming the data of an @model object type to Amazon Elasticsearch Service and configures search resolvers that search that information

@function
//  Allows you to quickly & easily configure AWS Lambda resolvers within your AWS AppSync API

@key
// Enables you to configure custom data access patterns for @model types

@versioned
// Adds object versioning and conflict resolution to a type

@http
// Allows you to quickly configure HTTP resolvers within your AWS AppSync API

Using this library you can deploy the back end for your application using only an annotated GraphQL schema.

In this post I will show example schemas that, when used with the Amplify GraphQL transform library, will build out the backends for many popular types of applications.

For a tutorial showing how to deploy these applications using the GraphQL transform library, check out the documentation here.

Some applications may require additional custom authorization logic for certain subscriptions that you may not want accessible to all users. To learn more, check out the documentation here.

Testing these out

To deploy any of these applications, run the following commands:

Be sure to first install the AWS Amplify CLI

$ amplify init
# Follow the steps to give the project a name, environment name, and set the default text editor.
# Accept defaults for everything else and choose your AWS Profile.

# If the app needs auth, add auth (choose the defaults)
$ amplify add auth

$ amplify add api

> Choose GraphQL
> If using authentication, choose Amazon Cognito as one of the authentication types
> Update GraphQL schema

# if the app needs storage (i.e. images or video)
$ amplify add storage

$ amplify push

Testing locally

You can now use local mocking to test serverless GraphQL APIs, databases, and serverless functions locally.

$ amplify mock

Check out this video for a quick overview of local testing:

Todo App

Let's start with something very basic: a Todo app.

This app has the following requirements. The user should be able to:

List all Todos
Create, update, and delete Todos

Based on these requirements we can assume we need the following for this application:

Todo type
Database
GraphQL definition for mutations (create, update, delete todos)
GraphQL definition for queries (listTodos)
GraphQL resolvers for all operations

To build this app, we could use the following annotated GraphQL schema:

type Todo @model {
  id: ID!
  name: String!
  description: String
}

This will deploy the entire GraphQL API including the DynamoDB NoSQL database, additional GraphQL schema for GraphQL CRUD and List operations, GraphQL subscriptions, and the GraphQL resolvers mapping the schema to the database.

Events App

Next, let's look at how we might create an events app. A point to notice here is that we will need to have a way for only Admins to be able to create, update, and delete events and public or other signed in users (non-Admins) to only be able to read events.

We also want to be able to query and get a sorted list (by date) of the events. There is also an optional Comment type that could be implemented to allow comments on an event and a one to many relationship enabled between events and comments using the @connection directive.

Based on these requirements, the user should be able to:

List events in order by date of event
View an individual event
Create a comment (signed in users only)
View comments on an event

An admin should also be able to:

Create an event
Update and delete an event

To build this app, we could use the following annotated GraphQL schema:

type Event @model
  @key(name: "itemType", fields: ["itemType", "time"], queryField: "eventsByDate")
  @auth(rules: [
    { allow: groups, groups: ["Admin"] },
    { allow: public, operations: [read] },
    { allow: private, operations: [read] }
  ]) {
    id: ID!
    name: String!
    description: String
    time: String!
    itemType: String!
    comments: [Comment] @connection #optional comments field
}

# Optional Comment type
type Comment @model
  @auth(rules: [
    { allow: owner, ownerField: "author" },
    { allow: public, operations: [read] },
    { allow: private, operations: [read] }
  ]) {
  id: ID!
  message: String!
  author: String
}

Creating an event

When creating a new event, we would need to populate the itemType parameter with a consistent value in order to be able to sort by time of the event:

mutation createEvent {
  createEvent(input: {
    name: "Rap battle of the ages"
    description: "You don't want to miss this!"
    time: "2018-07-13T16:00:00Z"
    itemType: "Event"
  }) {
    id name description time
  } 
}

Note: because itemType will be the same ("Event") value across all items, you could also update the resolver request mapping template to auto-populate this value and therefore not need to specify it in the mutation.

Now, to query for a list of sorted events, you could use the following query:

query listEvents {
  eventsByDate(itemType: "Event") {
    items {
      id
      name
      description
      time
    }
  }
}

Once you've created the authentication by running amplify add auth, you can run amplify console auth to add a user to the Admin group or use a Lambda Trigger to do it automatically when certain users sign up.

Creating a comment on an event

Using the eventCommentsId field, you can specify the event that you would like to associate with the comment:

mutation createComment {
  createComment(input: {
    eventCommentsId: "7f0d82f5-b57e-4417-b515-ce04475675a2"
    message:"Amazing!"
  }) {
    id
    message
  }
}

Chat app

In this example we'll look at how to create a basic chat app. For a more real-world chat-app that manages multiple users with authorization, check out the Multi-user Chat App example.

This app has the following requirements. The user should be able to:

Create a conversation
Create a message in a conversation
View all conversations and messages
Subscribe to new messages and conversations in real-time

type Conversation @model {
  id: ID!
  name: String
  messages: [Message] @connection(keyName: "messagesByConversationId", fields: ["id"])
  createdAt: String
  updatedAt: String
}

type Message
  @model(subscriptions: null, queries: null)
  @key(name: "messagesByConversationId", fields: ["conversationId"]) {
  id: ID!
  conversationId: ID!
  content: String!
  conversation: Conversation @connection(fields: ["conversationId"])
  createdAt: String
}

The following GraphQL queries and mutations would allow users to create a conversation, create a message in a conversation, and view all conversations and messages:

mutation createConversation {
  createConversation(input: {
    name: "my first conversation"
  }) {
    name
    id
  }
}

mutation createMessage {
  createMessage(input: {
    conversationId: "your-conversation-id"
    content: "Hello world"
  }) {
    id
    content
  }
}

query listConversations {
  listConversations {
    items {
      name
      messages {
        items {
          content
        }
      }
    }
  }
}

E-commerce App

This app has the following requirements. The Customer should be able to:

Create an account
View products
Create an order
Add line items to an order
View their account and all associated orders and items

An admin should be able to:

Create, update, and delete products, orders and customers
Fetch orders, products, and customers
Fetch orders by customer id

Based on these requirements we can assume we need the following for this application:

Product, Customer, Line Item, and Order types
Database tables for Products, Customers, Line Items, and Orders
GraphQL definition for mutations (create, update, delete products, customers, and orders)
GraphQL definition for queries (get, list)
GraphQL resolvers for all operations

To build this app, we could use the following annotated GraphQL schema:

type Customer @model(subscriptions: null)
  @auth(rules: [
    { allow: owner },
    { allow: groups, groups: ["Admin"] }
  ]) {
  id: ID!
  name: String!
  email: String!
  address: String
  orders: [Order] @connection(keyName: "byCustomerId", fields: ["id"])
}

type Product @model(subscriptions: null)
  @auth(rules: [
    { allow: groups, groups: ["Admin"] },
    { allow: public, operations: [read] },
    { allow: private, operations: [read] }
  ]) {
  id: ID!
  name: String!
  description: String
  price: Float!
  image: String
}

type LineItem @model(subscriptions: null)
  @key(name: "byOrderId", fields: ["orderId"])
  @auth(rules: [
   { allow: owner },
   { allow: groups, groups: ["Admin"] }
  ]) {
  id: ID!
  orderId: ID!
  productId: ID!
  qty: Int
  order: Order @connection(fields: ["orderId"])
  product: Product @connection(fields: ["productId"])
  description: String
  price: Float
  total: Float
}

type Order @model(subscriptions: null)
  @key(name: "byCustomerId", fields: ["customerId", "createdAt"], queryField: "ordersByCustomerId")
  @auth(rules: [
   { allow: owner },
   { allow: groups, groups: ["Admin"] }
  ]) {
  id: ID!
  customerId: ID!
  total: Float
  subtotal: Float
  tax: Float
  createdAt: String!
  customer: Customer @connection(fields: ["customerId"])
  lineItems: [LineItem] @connection(keyName: "byOrderId", fields: ["id"])
}

You should be able to now perform the following GraphQL operations against the API:

mutation createProduct {
  createProduct(input: {
    name: "Yeezys"
    description: "Best shoes ever"
    price: 200.00
  }) {
    id
    name
    description
    price
  }
}

mutation createCustomer {
  createCustomer(input: {
    name: "John Doe"
    email: "johndoe@myemail.com"
    address: "555 Hwy 88"
  }) {
    id
    email
    name
    address
  }
}

mutation createOrder {
  createOrder(input: {
    subtotal: 250.00
    total: 275.00
    tax: 25.00
    customerId: "some-customer-id"
  }) {
    id
    subtotal
    tax
    total
    customer {
      name
    }
  }
}

mutation createLineItem {
  createLineItem(input: {
    qty: 1
    productId: "some-product-id"
    orderId: "some-order-id"
    price: 250.00
    total: 250.00
  }) {
    id
    qty
  }
}

query getCustomer {
  getCustomer(id: "some-customer-id") {
    id
    name
    address
    orders {
      items {
        id
        lineItems {
          items {
            description
            price
            total
            qty
            product {
              id
              name
              description
            }
          }
        }
      }
    }
  }
}

query ordersByCustomerId {
  ordersByCustomerId(
    customerId: "some-customer-id"
  ) {
    items {
      id
      lineItems {
        items {
          id
          price
          total
        }
      }
      total
      subtotal
      tax
    }
  }
}

query listOrders {
  listOrders {
    items {
      id
      total
      subtotal
      tax
      lineItems {
        items {
          id
          price
          product {
            id
            price
            description
          }
        }
      }
    }
  }
}

WhatsApp Clone

This app has the following requirements. The User should be able to:

Create an account
Update their profile with their avatar image
Create a conversation
Create a message in a conversation

Based on these requirements we can assume we need the following for this application:

User, Conversation, and Message types
Database tables for Users, Conversations, and Messages
GraphQL definition for mutations (create, update, delete users, conversations, and messages)
GraphQL definition for queries
GraphQL subscriptions for real-time communication
GraphQL resolvers for all operations

To build this app, we could use the following annotated GraphQL schema:

type User
  @key(fields: ["userId"])
  @model(subscriptions: null)
  @auth(rules: [
    { allow: owner, ownerField: "userId" }
  ]) {
  userId: ID!
  avatar: String
  conversations: [ConvoLink] @connection(keyName: "conversationsByUserId", fields: ["userId"])
  messages: [Message] @connection(keyName: "messagesByUserId", fields: ["userId"])
  createdAt: String
  updatedAt: String
}

type Conversation
  @model(subscriptions: null)
  @auth(rules: [{ allow: owner, ownerField: "members" }]) {
  id: ID!
  messages: [Message] @connection(keyName: "messagesByConversationId", fields: ["id"])
  associated: [ConvoLink] @connection(keyName: "convoLinksByConversationId", fields: ["id"])
  members: [String!]!
  createdAt: String
  updatedAt: String
}

type Message
  @key(name: "messagesByConversationId", fields: ["conversationId"])
  @key(name: "messagesByUserId", fields: ["userId"])
  @model(subscriptions: null, queries: null) {
  id: ID!
  userId: ID!
  conversationId: ID!
  author: User @connection(fields: ["userId"])
  content: String!
  image: String
  conversation: Conversation @connection(fields: ["conversationId"])
  createdAt: String
  updatedAt: String
}

type ConvoLink
  @key(name: "convoLinksByConversationId", fields: ["conversationId"])
  @key(name: "conversationsByUserId", fields: ["userId"])
  @model(
    mutations: { create: "createConvoLink", update: "updateConvoLink" }
    queries: null
    subscriptions: null
  ) {
  id: ID!
  userId: ID!
  conversationId: ID!
  user: User @connection(fields: ["userId"])
  conversation: Conversation @connection(fields: ["conversationId"])
  createdAt: String
  updatedAt: String
}

type Subscription {
  onCreateConvoLink(userId: ID): ConvoLink
    @aws_subscribe(mutations: ["createConvoLink"])
  onCreateMessage(conversationId: ID): Message
    @aws_subscribe(mutations: ["createMessage"])
}

Reddit Clone

This app has the following requirements. The User should be able to:

Create an account
Create & delete a post (post can be an image or text)
Comment on a post
Vote on a post
Vote on a comment

Based on these requirements we can assume we need the following for this application:

User, Post, Comment, and Vote types
Database
GraphQL definition for mutations (create, update, delete users, posts and comments)
GraphQL definition for queries
GraphQL resolvers for all operations

To build this app, we could use the following annotated GraphQL schema:

type User @model(subscriptions: null)
  @key(fields: ["userId"])
  @auth(rules: [
    { allow: owner, ownerField: "userId" }
  ]) {
  userId: ID!
  posts: [Post] @connection(keyName: "postByUser", fields: ["userId"])
  createdAt: String
  updatedAt: String
}

type Post @model
  @key(name: "postByUser", fields: ["authorId", "createdAt"])
  @auth(rules: [
    { allow: owner, ownerField: "authorId" },
    { allow: public, operations: [read] },
    { allow: private, operations: [read] }
  ]) {
  id: ID!
  authorId: ID!
  author: User @connection(fields: ["authorId"])
  postContent: String
  postImage: String
  comments: [Comment] @connection(keyName: "commentsByPostId", fields: ["id"])
  votes: [PostVote] @connection(keyName: "votesByPostId", fields: ["id"])
  createdAt: String
  voteCount: Int
}

type Comment @model
  @key(name: "commentsByPostId", fields: ["postId"])
  @auth(rules: [
    { allow: owner, ownerField: "authorId" },
    { allow: public, operations: [read] },
    { allow: private, operations: [read] }
  ]) {
  id: ID!
  authorId: ID!
  postId: ID!
  text: String!
  author: User @connection(fields: ["authorId"])
  votes: [CommentVote] @connection(keyName: "votesByCommentId", fields: ["id"])
  post: Post @connection(fields: ["postId"])
  voteCount: Int
}

type PostVote @model
  @auth(rules: [
    { allow: owner, ownerField: "userId"},
    { allow: public, operations: [read] },
    { allow: private, operations: [read] }
  ])
  @key(name: "votesByPostId", fields: ["postId"]) {
  id: ID!
  postId: ID!
  userId: ID!
  post: Post @connection(fields: ["postId"])
  createdAt: String!
  vote: VoteType
}

type CommentVote @model
  @auth(rules: [
    { allow: owner, ownerField: "userId"},
    { allow: public, operations: [read] },
    { allow: private, operations: [read] }
  ])
  @key(name: "votesByCommentId", fields: ["commentId"]) {
  id: ID!
  userId: ID!
  commentId: ID!
  comment: Comment @connection(fields: ["commentId"])
  createdAt: String!
  vote: VoteType
}

input VoteInput {
  type: VoteType!
  id: ID!
}

enum VoteType {
  up
  down
}

This implementation will prevent users from voting multiple times, but you must implement a custom resolver to set the vote ID as a combination of the postId and the user's userId.

The most secure way to do this would be on the server, by reading the user's userId from their JWT. To do so, you could first use these two lines of code to set the vote ID to be the unique combination of the itemId and the user's ID:

#set($itemId = "$context.identity.username#$context.args.postId")
$util.qr($context.args.input.put("id", $util.defaultIfNull($ctx.args.input.id, $itemId)))

Then, delete or comment out the conditional expression code that does not allow the vote to be overridden:

#set( $condition = {
  "expression": "attribute_not_exists(#id)",
  "expressionNames": {
      "#id": "id"
  }
} )

Vote aggregation

If you would like to implement either a vote count total or some type of algorithmic vote count of your own choosing, you can enable a DynamoDB trigger to invoke a Lambda function where you can write your own custom logic.

Here is an example of a DynamoDB trigger that implements an atomic counter, similar to what you would probably want to do in a situation where you need to be sure votes are incremented or decremented consistently.

Multi-user Chat App

This app has the following requirements. The User should be able to:

Create an account
Create a conversation
Create a message in a conversation
View a list of all conversations
Have the ability to create a new conversation with another user

Based on these requirements we can assume we need the following for this application:

User, Conversation, and Messsage types
Database
GraphQL definition for mutations (create, update, delete users, conversations and messages)
GraphQL definition for queries
GraphQL resolvers for all operations

To build this app, we could use the following annotated GraphQL schema:

type User
  @key(fields: ["userId"])
  @model(subscriptions: null)
  @auth(rules: [
    { allow: owner, ownerField: "userId" }
  ]) {
  userId: ID!
  conversations: [ConvoLink] @connection(keyName: "conversationsByUserId", fields: ["userId"])
  messages: [Message] @connection(keyName: "messagesByUserId", fields: ["userId"])
  createdAt: String
  updatedAt: String
}

type Conversation
  @model(subscriptions: null)
  @auth(rules: [{ allow: owner, ownerField: "members" }]) {
  id: ID!
  messages: [Message] @connection(keyName: "messagesByConversationId", fields: ["id"])
  associated: [ConvoLink] @connection(keyName: "convoLinksByConversationId", fields: ["id"])
  members: [String!]!
  createdAt: String
  updatedAt: String
}

type Message
  @key(name: "messagesByConversationId", fields: ["conversationId"])
  @key(name: "messagesByUserId", fields: ["userId"])
  @model(subscriptions: null, queries: null) {
  id: ID!
  userId: ID!
  conversationId: ID!
  author: User @connection(fields: ["userId"])
  content: String!
  conversation: Conversation @connection(fields: ["conversationId"])
  createdAt: String
  updatedAt: String
}

type ConvoLink
  @key(name: "convoLinksByConversationId", fields: ["conversationId"])
  @key(name: "conversationsByUserId", fields: ["userId"])
  @model(
    mutations: { create: "createConvoLink", update: "updateConvoLink" }
    queries: null
    subscriptions: null
  ) {
  id: ID!
  userId: ID!
  conversationId: ID!
  user: User @connection(fields: ["userId"])
  conversation: Conversation @connection(fields: ["conversationId"])
  createdAt: String
  updatedAt: String
}

type Subscription {
  onCreateConvoLink(userId: ID): ConvoLink
    @aws_subscribe(mutations: ["createConvoLink"])
  onCreateMessage(conversationId: ID): Message
    @aws_subscribe(mutations: ["createMessage"])
}

Instagram Clone

This app has the following requirements. The User should be able to:

Create an account
Create a post
Create a comment on a post
Follow and unfollow a user
Like a comment or a post

Based on these requirements we can assume we need the following for this application:

User, Post, Like, Following, and Comment types
Database
GraphQL definition for mutations (create, update, delete users, posts, comments, following, and likes)
GraphQL definition for queries
GraphQL resolvers for all operations

To build this app, we could use the following annotated GraphQL schema:

type User @model(subscriptions: null)
  @key(fields: ["userId"])
  @auth(rules: [
    { allow: owner, ownerField: "userId" },
    { allow: private, operations: [read] }
    ]) {
  userId: ID!
  posts: [Post] @connection(keyName: "postsByUserId", fields: ["userId"])
  createdAt: String
  updatedAt: String
  following: [Following] @connection(keyName: "followingByUserId", fields: ["userId"])
}

type Post @model
  @key(name: "postsByUserId", fields: ["authorId"])
  @auth(rules: [
    { allow: owner ownerField: "authorId" },
    { allow: public, operations: [read] },
    { allow: private, operations: [read] }
  ]) {
  id: ID!
  authorId: ID!
  content: String!
  postImage: String
  author: User @connection(fields: ["authorId"])
  comments: [Comment] @connection(keyName: "commentsByPostId", fields: ["id"])
  likes: [PostLike] @connection(keyName: "postLikesByPostId", fields: ["id"])
}

type Comment @model
  @key(name: "commentsByPostId", fields: ["postId"])
  @auth(rules: [
    { allow: owner, ownerField: "authorId" },
    { allow: public, operations: [read] },
    { allow: private, operations: [read] }
  ]) {
  id: ID!
  postId: ID!
  authorId: ID!
  text: String!
  likes: [CommentLike] @connection(keyName: "commentLikesByCommentId", fields: ["id"])
  author: User @connection(fields: ["authorId"])
  post: Post @connection(fields: ["postId"])
}

type PostLike @model
  @auth(rules: [
    { allow: owner, ownerField: "userId" },
    { allow: public, operations: [read] },
    { allow: private, operations: [read] }
  ])
  @key(name: "postLikesByPostId", fields: ["postId"])
  @key(name: "postLikesByUser", fields: ["userId", "createdAt"], queryField: "likesByUser") {
  id: ID!
  postId: ID!
  userId: ID!
  user: User @connection(fields: ["userId"])
  post: Post @connection(fields: ["postId"])
  createdAt: String!
}

type CommentLike @model
  @auth(rules: [
    { allow: owner, ownerField: "userId" },
    { allow: public, operations: [read] },
    { allow: private, operations: [read] }
  ])
  @key(name: "commentLikesByCommentId", fields: ["commentId"])
  @key(name: "commentLikesByUser", fields: ["userId", "createdAt"], queryField: "likesByUser") {
  id: ID!
  userId: ID!
  postId: ID!
  commentId: ID!
  user: User @connection(fields: ["userId"])
  post: Post @connection(fields: ["postId"])
  createdAt: String!
}

type Following @model
  @auth(rules: [
    { allow: owner, ownerField: "followerId" },
    { allow: public, operations: [read] },
    { allow: private, operations: [read] }
  ])
  @key(name: "followingByUserId", fields: ["followerId"]) {
  id: ID
  followerId: ID!
  followingId: ID!
  follower: User @connection(fields: ["followerId"])
  following: User @connection(fields: ["followingId"])
  createdAt: String!
}

Likes

Similarly to the Reddit clone, we need to have some custom logic in our resolver to handle likes. To see how this works, check out the custom resolver in the Reddit Clone

Conference App

Click here to view Conference App in a Box, a completed full-stack version of this app built with React Native.

This app has the following requirements. The User should be able to:

Create an account
View a list of talks
View an individual talk
Create a comment on a talk
(optional) Report a comment

An Admin should be able to:

Create, edit, and delete a talk

Based on these requirements we can assume we need the following for this application:

Talk, Comment, and (optional) Report types
Database
GraphQL definition for mutations (create, update, delete talks, comments, and reports)
GraphQL definition for queries
GraphQL resolvers for all operations

To build this app, we could use the following annotated GraphQL schema:

type Talk @model
  @auth(rules: [
    { allow: groups, groups: ["Admin"] },
    { allow: public, operations: [read] },
    { allow: private, operations: [read] }
  ]) {
  id: ID!
  name: String!
  speakerName: String!
  speakerBio: String!
  time: String
  timeStamp: String
  date: String
  location: String
  summary: String!
  twitter: String
  github: String
  speakerAvatar: String
  comments: [Comment] @connection(keyName: "commentsByTalkId", fields: ["id"])
}

type Comment @model
  @key(name: "commentsByTalkId", fields: ["talkId"])
  @auth(rules: [
    { allow: owner, ownerField: "authorId" },
    { allow: public, operations: [read] },
    { allow: private, operations: [read] }
  ])
{
  id: ID!
  talkId: ID!
  talk: Talk @connection(fields: ["talkId"])
  message: String
  createdAt: String
  authorId: ID!
  deviceId: ID
}

type Report @model
  @auth(rules: [
    { allow: owner, operations: [create, update, delete] },
    { allow: groups, groups: ["Admin"] }
  ])
  {
  id: ID!
  commentId: ID!
  comment: String!
  talkTitle: String!
  deviceId: ID
}

type ModelCommentConnection {
  items: [Comment]
  nextToken: String
}

type Query {
  listCommentsByTalkId(talkId: ID!): ModelCommentConnection
}

type Subscription {
  onCreateCommentWithId(talkId: ID!): Comment
        @aws_subscribe(mutations: ["createComment"])
}

In this schema, notice we are adding an additional subscription to listen to new comments by ID. This way we can only subscribe to comments for the talk that we are currently viewing.

Conclusion

My Name is Nader Dabit. I am a Developer Advocate at Amazon Web Services working with projects like AWS AppSync and AWS Amplify. I specialize in cross-platform & cloud-enabled application development.

How to resolve import for the .graphql file with typescript and webpack

Mohsen ZareZardeyni — Wed, 10 Jul 2019 18:26:18 +0000

Hi, I’m Mohsen ZareZardeyni, and I’m a software engineer at Sigma Telecom LLC.

At Sigma, for developing our back office application, we decided to use GraphQL, Typescript and Apollo server. We choose Schema first approach and stored our schema in separate .graphql files. In order to import our schema within our Typescript code, we ended up using Webpack as our transpiler.

As I was looking for a way to do so, I didn’t find any good tutorial on this matter so I’m providing this tutorial for future researchers!🤠

First, you need to add the following configuration to your tsconfig.json. This will tell Typescript to use the src/@types folder in addition to node_modules/@types in order to identify your types.

Then you need to introduce .graphql files to Typescript. In order to do this, you need to create a graphql.d.ts in your src/@types folder. The following code will tell typescript every time it sees an imported file with the .graphql extension, it will provide a GraphQL DocumentNode, which is the type you need to provide for your GraphQL Schema.

In our case, we used apollo-server from Apollo Foundation, but any other GraphQL server library uses the same pattern. With previous steps, the following code will let you import your .graphql files without any typing issue.

Finally, the last step is to tell webpack how to treat .graphql imports. The following code will tell webpack every time it sees a .graphql file, it should use graphql-tag/loader in order to load the content.

Hope this helps you:)

Also, you can find me on linkedin and twitter.

GraphQLifying REST

Nader Dabit — Wed, 10 Jul 2019 15:50:25 +0000

When adopting GraphQL into an existing project or an engineering team, one of the easiest ways to get started is to put a GraphQL API in front of your existing REST API endpoints.

Doing this will allow your team to immediately begin seeing some of the benefits that GraphQL has to offer without having to sacrifice a large amount of engineering work.

With AWS AppSync you can specify “HTTP” data sources to bring in existing HTTP endpoints & perform queries & mutations against them in GraphQL.

Let’s take a look at how we can port over these two types of HTTP APIs:

**Cryptocurrency API **that returns an array of data & allows us to query based on limit & starting point for pagination.
GitHub Jobs API that returns an array of jobs. We need to be able to query based on location & job description.

Let’s start building!

Getting Started

The first step is to create a new AWS AppSync API. To do so, visit the AppSync dashboard & click Create API.

Next, choose Build from scratch & click Next.

Build from scratch

Next, give your AppSync API a name & click Create.

Building a Cryptocurrency GraphQL API

Now that we’ve created the AppSync API, we will need to add our first data source.

The first API we’ll be converting will be the Coinlore API.

In the left menu of your AppSync API click on Data Sources.

Next, click Create data source.

Here, give the data source a name of CryptoAPI, a Data source type of HTTP Endpoint, & an HTTP Endpoint of **https://api.coinlore.com then click **Create.

Now that we’ve created our data source, let’s take a look at some of the requests that we’ll be making to the API:

https://api.coinlore.com/api/tickers/
https://api.coinlore.com/api/tickers/?start=100
https://api.coinlore.com/api/tickers/?limit=100

Next, let’s take a look at the data structure that we’ll be working with:

{
  data: [
    {
      id: "90",
      symbol: "BTC",
      name: "Bitcoin",
      nameid: "bitcoin",
      rank: 1,
      price_usd: "6943.53",
      ...
    },
    {
      id: "80",
      symbol: "ETH",
      name: "Ethereum",
      nameid: "ethereum",
      rank: 2,
      price_usd: "186.20",
      ...
    }
  ],
  info: {
    coins_num: 2148,
    time: 1557709606
  }
}

We will want to access the data array. With that in mind, we can create a GraphQL type in our schema (Coin) that corresponds to the objects in the data as well as a query that will fetch & return an array of the new type.

To create this new type & query click on Schema in the left menu, enter the following schema, & then click Save.

type Coin {
 symbol: String
 name: String
 rank: String
 price_usd: String
}

type Query {
 listCoins(limit: Int, start: Int): [Coin]
 listCoinsJSON: AWSJSON
}

You’ll notice that the listCoins query has an optional limit & start argument that we’ll need to handle in the resolver.

Now that we’ve defined our schema, let’s create a resolver for the listCoins query. To do so, find the listCoins query in the resolvers list on the right hand side of the schema in the Schema view. Next, click on Attach.

The resolver consists of three parts:

Data source — Defines the data source for the resolver
*Request mapping template *— Takes the incoming request after a GraphQL operation is parsed and converts it into a request configuration for the selected data source operation.
Response mapping template — Interprets responses from your data source and maps to the shape of the GraphQL field output type

For the data source, choose the CryptoAPI data source we created earlier.

For the request mapping template, use the following request mapping template:

{
  "version": "2018-05-29",
  "method": "GET",
  "resourcePath": "/api/tickers/",
  "params": {
      "query": $util.toJson($ctx.args)
  }
}

The method can be either PUT, POST, GET, DELETE, or PATCH. The resourcePath is the path of the url that you’d like to hit. The params are where you can specify query params (query), headers (headers), & the body (body) for PUT, POST, or PATCH operations.

In the query params of the above request mapping template you will see that we are specifying the $ctx.args as the query. This will allow us to pass in any arguments to the GraphQL query & they will be mapped into query parameters.

For the response mapping template, use the following:

#set($body = $util.parseJson($ctx.result.body))
$util.toJson($body.data)

This response mapping template will parse the data & return the data property in the form of JSON back to us.

Save the new resolver & then click Queries in the left menu.

To test the new resolver, we can try out the following queries:

query listCoins {
  listCoins {
    price_usd
    name
    symbol
    rank
  }
}

query listCoinsJSON {
  listCoinsJSON
}

query listCoins {
  listCoins(limit: 5) {
    price_usd
    name
    symbol
    rank
  }
}

query listCoins {
  listCoins(start: 10) {
    price_usd
    name
    symbol
    rank
  }
}

All of these queries should work for you, returning different subsets of the data from the API.

Congratulations, you’ve successfully migrated your first REST API to GraphQL!

Building a GitHub Jobs GraphQL API

Next, let’s look at how we can fetch the jobs data from the GitHub Jobs API.

The API endpoints we will be working with are:

https://jobs.github.com/positions.json
https://jobs.github.com/positions.json?location=remote
https://jobs.github.com/positions.json?description=react
https://jobs.github.com/positions.json?search=javascript&page=2

To get started, create a new HTTP data source called GitHubJobsAPI & set the HTTP endpoint to https://jobs.github.com.

The data returned from the API call looks like this:

[
  {
    type: "Full Time",
    url: "[https://jobs.github.com/positions/9636b280-e12a-11e8-819f-7c947fed1ee2](https://jobs.github.com/positions/9636b280-e12a-11e8-819f-7c947fed1ee2)",
    company: "Homestars",
    location: "Toronto",
    title: "Salesforce Engineer ",
    description: "WHO WE ARE: Canadians spend...."
  },
  {
    type: "Contract",
    url: "[https://jobs.github.com/positions/8c96ec9e-e130-11e8-9bb2-d87985623e61](https://jobs.github.com/positions/8c96ec9e-e130-11e8-9bb2-d87985623e61)",
    created_at: "Mon Nov 05 19:26:48 UTC 2018",
    company: "Rifle Paper Co.",
    location: "Remote",
    title: "FREELANCE PHP DEVELOPER",
    description: "OVERVIEW: We are...
  }
]

Let’s create a GraphQL type in our schema (Job) that corresponds to the objects in the array as well as a query that will fetch & return an array of the new Job type. We’ll also create an input for the arguments that we will be passing in to the query. Add the following to the schema, & then click Save.

type Job {
 title: String
 description: String
 url: String
 type: String
 company: String
 location: String
}

input JobsInput {
 page: String
 description: String
 location: String
 search: String
}

type Query {
  listJobs(query: JobsInput): [Job]
}

Now that we’ve defined our schema, let’s create a resolver for the listJobs query. To do so, find the listJobs query in the resolvers list on the right hand side of the schema in the Schema view. Next, click on Attach.

For the data source, choose the GitHubJobsAPI data source we created earlier.

For the request mapping template, use the following:

{
  "version": "2018-05-29",
  "method": "GET",
  "resourcePath": "/positions.json",
  "params":{
      "query":$util.toJson($ctx.args.query)
  }
}

For the response mapping template, use the following:

#set($body = $util.parseJson($ctx.result.body))
$util.toJson($body)

Like the listCoins response mapping template, this response mapping template will parse the data & return the data property in the form of JSON back to us.

Save the new resolver & then click Queries in the left menu.

To test the new resolver, we can try out the following queries:

query listJobs {
  listJobs(query: {
    search: "javascript"
    page: "3"
  }) {
    title
    location
    description
  }
}

query listJobs {
  listJobs(query: {
    location: "remote"
  }) {
    title
    location
    description
  }
}

query listJobs {
  listJobs(query: {
    description: "react native"
  }) {
    title
    location
    description
  }
}

Next Steps

The two examples we covered only went over GET requests. What if you wanted to do a POST, PUT, PATCH, or DELETE?

The main difference would be in the request mapping template. Here is where you can define your method as well as pass in any headers or body to the request.

Let’s look at how we might pass in data in the body using a POST request.

First, let’s take a look at the mutation definition:

createItem(body: STRING): [Item]

Next, let’s take a look at the request mapping template:

{
  "version": "2018-05-29",
  "method": "POST",
  "resourcePath": "/api/yourapi/",
  "params": {
      "body": $ctx.args.body
  }
}

How about passing in headers / authorization headers?

#set($authHeader = "Bearer " + "SOMETOKEN")

{

  "version": "2018-05-29",

  "method": "POST",

  "resourcePath": "/api/yourapi/",

  "params": {

      "body": $ctx.args.body,

      "headers": {

        "Content-Type": "application/json",

        "Authorization": $authHeader

      }

  }

}

Conclusion

To view a video walkthrough of how to do this, check out this video:

Though we are currently working on it, as of this post, the Amplify CLI does not have direct support for HTTP resolvers. Support should be released soon, & when it is I’ll update this post to show how to do this with the Amplify CLI.

If you’d like to learn more about working with HTTP resolvers, check out the documentation here & the HTTP Resolvers tutorial here.

My Name is Nader Dabit. I am a Developer Advocate at Amazon Web Services working with projects like AWS AppSync and AWS Amplify. I specialize in cross-platform & cloud-enabled application development.

DEV Community: Open GraphQL

Feature Flag approach with GraphQL and React 🕹

Storage

API

Querying

useFeatureFlag

Caching and better UX

What is next?

Migrate from Graphcool to Hasura

Pre-requisites:

Step 1: Export data from Graph.cool

Step 2: Set up an intermediary MySQL server

Step 2.1: Start MySQL with Docker

Step 2.2: Connect to MySQL via mysql CLI

Step 2.3: Create a database in MySQL

Step 2.4: Import data

Step 3: Migrate data to Hasura

Step 3.1: Set up Hasura

Step 3.2: Import data into Postgres

Step 3.3: Connect Hasura to Postgres

Step 4: Migrate structure & functionality

Step 4.1: Restructure connection tables

Step 4.2: Migrate functions

Step 4.3: Migrate auth

Step 4.4: Migrate permissions

Community Tooling for File Storage

Subscriptions

Building Dad Jokes using The Prisma Framework (formerly Prisma 2) and React Native

Prerequisites

Server-Side (The Prisma Framework)

Start a new Prisma 2 project

Run the interactive prisma2 init flow & select boilerplate

Migrate your database with Lift

List all jokes

Find A Particular Joke

Create A Joke

Delete a joke

Client-Side (React Native)

Bootstrap a new Expo project

React Navigation

GraphQL Queries and Mutations

Screens

Home Screen

Add Joke Screen

Conclusion

Building Powerful GraphQL Servers with Rust

Setting up an HTTP Server

Creating the GraphQL Schema

Exposing the Schema

Setting up Postgres for Real Data

Wiring up our Handlers with Diesel

The Create Member Mutation

Thanks For Reading

Other Neat Reading Material

GraphQL and Urql by Example

Comparison between Apollo and Urql

Setting up the GraphQL server

Getting Started with Urql

Querying data in Urql using Render Props or React Hooks

Mutating data in Urql using Render Props or React Hooks

What are Exchanges in Urql

Subscribing to data in Urql using Render Props or React Hooks

Conclusion

Multiple Apollo Clients in React

Why would we need multiple Apollo clients?

⭐️ First Solution

What would be the ideal approach then?

Solving the problem in the Frontend

Community implementations

Client-side schema stitching

Gateways for Frontends

Schema Stitching

Apollo Federation

Conclusion

GraphQL Recipes (V2) - Building APIs with GraphQL Transform

Testing these out

Testing locally

Todo App

Events App

Creating an event

Run the interactive `prisma2 init` flow & select boilerplate