DEV Community: Eve Porcello

How Do I Livecode Without Panicking?

Eve Porcello — Thu, 18 Mar 2021 21:02:26 +0000

Have you ever seen a mind-melting technical talk where someone was livecoding and you thought "That's cool, but I could never do that." Or maybe you thought: "I'll do that, but later in my life when I am more established. And no I'm not saying when." Or "That amazing speaker is just better than me. I can't do that because I am not a witch."

The truth is that amazing speaker isn't better than you. That amazing speaker probably just has notes.

When preparing a talk where you want to incorporate a bit of livecoding, consider a few steps:

1. Build a Demo

Put together a demo of what you want to present. Test it. Make sure it works. Refactor the code until you're ready to show it off.

2. Decide Which Pieces to Livecode

Does everyone want to see you build every single file? Maybe but probably not. Stay focused on the parts that matter to the overall message of your talk.

3. Create Your Notes

For my talks and workshops, I create markdown files for notes that can be clicked through as steps. The less thinking the better. Type one step. Click Next. Type the next step. Click Next.

This means that there's no question about what I should be doing at any given moment. Plus, I am never frantically scrolling through a long markdown file because I have lost my place. Creating separate files for each step takes longer, but I've never regretted the peace of mind that it brings.

4. Practice with Your Notes (Over and Over Again)

Once you've created your notes, run through your presentation lots of times. Run through it yourself. Record yourself doing it. Present in front of friends or family members or coworkers. As you practice, make sure that your notes reflect what you're actually doing and contain no mistakes.

Keep your notes on a second screen if you're presenting remotely or on an iPad/tablet if you're presenting in person.

5. Present with your Trusty Notes (+ a Baked Version)

Will you be nervous when you give your talk? Of course you will be. But with your notes, you'll have a trail map for where you're headed, and you'll feel prepared. More often than not, preparing in this detailed fashion will save you from unfortunate crashes. If something goes wrong, you can always pull out a complete version of the project and show people around the files.

6. Do It Again

Now you can give the same presentation somewhere else because you have such good notes.

Livecoding works. It's engaging and interactive because the audience wants to see if you can do it. When you rehearse and bring your notes, you'll bring your confidence. No magic beans required.

Incorporating REST Data with a GraphQL API

Eve Porcello — Sat, 10 Oct 2020 02:19:57 +0000

One popular misconception about GraphQL is that you have to tear down all of your REST APIs in order to build a GraphQL server. The flexibility of GraphQL allows you to use all of your favorite REST data sources while enjoying the organizational benefits of a GraphQL schema. In this article, we'll take a closer look at how we can incorporate the data from a REST API into an existing GraphQL server.

The server in question is the Snowtooth API, a real GraphQL API for a fake ski resort. With this API, we host data about two types: Lifts and Trails, and the app provides lift status and trail status for the ski resort. We want to update this API to include data from the Strava API. Strava is an app that allows you to track your activities like bike rides, hikes, and, of course, ski days. Strava exposes a REST API that we're going to consume with our app.

Create a Type in the Schema

To start, we'll look at the data from the Strava API and create a type that models the data. Strava's data type that we want to model is the Activity type, so we'll choose the fields we want using GraphQL's schema definition language:

type Activity {
  id: ID!
  name: String
  distance: Float
  type: String
  time: Int
}

While the Strava API gives us more fields than that, we'll only create GraphQL fields for the fields we want.

Add a Field to the `Query` Type

In our app, we want to be able to send queries for the data from Strava. To do so, we'll create a query called myActivities that returns a list of activities:

type Query {
    ...
    myActivities: [Activity!]!
}

We'll make Activity non-nullable in this case, meaning that myActivities can't return null and all values within the returned array must be non-null. If myActivities returns an empty array, this will be valid because an empty array is not a null value.

Create a Resolver for `myActivities`

Next, we'll create the query resolver for the Query.myActivities field. Resolvers are functions that return data for specific fields. Resolvers can be asynchronous and can fetch directly from REST APIs. We'll include node-fetch to help us with this task, but you can use isomorphic-fetch, axios, or whatever your favorite fetching tool is from npm:

npm install node-fetch

Then we'll use this in the resolver, and to handle the asynchronous nature of the request, we'll use async/await syntax:

const resolvers = {
  Query: {
    myActivities: async () => {
      let results = await fetch(
        'https://www.strava.com/api/v3/activities?per_page=100'
      ).then(r => r.json());

      return results;
    }
  }
};

We're looking to return an array of activities, so we can just convert the response to JSON and return it.

Pass Authorization Headers

The final step is that we need to get an auth token from Strava and pass that via the request's headers. To obtain a token, you'll visit the Strava API docs and follow the instructions.

Then you can pass that token directly via the second argument sent to the fetch function:

const resolvers = {
  Query: {
    myActivities: async () => {
      let results = await fetch(
        'https://www.strava.com/api/v3/activities?per_page=100',
        {
          headers: {
            Authorization: 'Bearer <Your_Strava_Token_here>'
          }
        }
      ).then(r => r.json());

      return results;
    }
  }
};

Replace the bit with your own token.

Fetching data from a REST API is a pretty common task when we're building GraphQL services, and usually the fastest way to get started is to incorporate fetch!

If you'd like to review the project, you can check out the repo.

Securing Your GraphQL Server

Eve Porcello — Tue, 06 Oct 2020 03:07:15 +0000

When you build a GraphQL API, you provide a lot of freedom and flexibility to your clients. They have the flexibility to query data from multiple sources in a single request. They also have the ability to request large amounts of related, or connected, data in a single request. Left unchecked, your clients could have the capability of requesting too much from your service. Not only will the strain of large queries affect server performance, it could also take your service down entirely. Some clients might do this unintentionally, whereas other clients might have more malicious intent. Either way, you need to put some safeguards in place and monitor your server’s performance in order to protect against large or malicious queries.

In this article, we'll cover some of the options available to improve the security of your GraphQL service.

Request Timeouts

A request timeout is a first defense against large or malicious queries. A request time‐ out allows only a certain amount of time to process each request. This means that requests of your service need to be completed within a specific time frame. Request timeouts are used not only for GraphQL services, they are used for all sorts of services and processes across the internet. You might have already implemented these timeouts for your Representational State Transfer (REST) API to guard against lengthy requests with too much POST data.

You can add an overall request timeout to the express server by setting the timeout key. In the following, we’ve added a timeout of five seconds to guard against troublesome queries:

const httpServer = createServer(app);
server.installSubscriptionHandlers(httpServer);
httpServer.timeout = 5000;

Additionally, you can set timeouts for overall queries or individual resolvers. The trick to implementing timeouts for queries or resolvers is to save the start time for each query or resolver and validate it against your preferred timeout. You can record the start time for each request in context:

const context = async ({ request }) => {
  return {
    timestamp: performance.now()
  };
};

Now each of the resolvers will know when the query began and can throw an error if the query takes too long.

Data Limitations

Another simple safeguard that you can place against large or malicious queries is to limit the amount of data that can be returned by each query. You can return a specific number of records, or a page of data, by allowing your queries to specify how many records to return.

We can design schemas to allow for pagination. But what if a client requested an extremely large page of data? Here’s an example of a client doing just that:

query allPhotos {
  allPhotos(first=99999) {
    name
    url
    postedBy {
      name
      avatar
    }
  }
}

You can guard against these types of large requests by simply setting a limit for a page of data. For example, you could set a limit for 100 photos per query in your GraphQL server. That limit can be enforced in the query resolver by checking an argument:

allPhotos: (parent, data, context) {
  if (data.first > 100) {
    throw new Error('Only 100 photos can be requested at a time');
  }
}

When you have a large number of records that can be requested, it is always a good idea to implement data paging. You can implement data paging simply by providing the number of records that should be returned by a query.

Limiting Query Depth

One of the benefits GraphQL provides the client is the ability to query connected data. For example, in our photo API, we can write a query that can deliver information about a photo, who posted it, and all the other photos posted by that user all in one request:

query getPhoto($id: ID!) {
  Photo(id: $id) {
    name
    url
    postedBy {
      name
      avatar
      postedPhotos {
        name
        url
      }
    }
  }
}

This is a really nice feature that can improve network performance within your applications. We can say that the preceding query has a depth of 3 because it queries the photo itself along with two connected fields: postedBy and postedPhotos. The root query has a depth of 0, the Photo field has a depth of 1, the postedBy field has a depth of 2 and the postedPhotos field has a depth of 3.
Clients can take advantage of this feature. Consider the following query:

query getPhoto($id: ID!) {
  Photo(id: $id) {
    name
    url
    postedBy {
      name
      avatar
      postedPhotos {
        name
        url
        taggedUsers {
          name
          avatar
          postedPhotos {
            name
            url
          }
        }
      }
    }
  }
}

We’ve added two more levels to this query’s depth: the taggedUsers in all of the photos posted by the photographer of the original photo, and the postedPhotos of all of the taggedUsers in all of the photos posted by the photographer of the original photo. This means that if I posted the original photo, this query would also resolve to all of the photos I’ve posted, all of the users tagged in those photos, and all of the photos posted by all of those tagged users. That’s a lot of data to request. It is also a lot of work to be performed by your resolvers. Query depth grows exponentially and can easily get out of hand.

You can implement a query depth limit for your GraphQL services to prevent deep queries from taking your service down. If we had set a query depth limit of 3, the first query would have been within the limit, whereas the second query would not because it has a query depth of 5.

Query depth limitations are typically implemented by parsing the query’s AST and determining how deeply nested the selection sets are within these objects. There are npm packages like graphql-depth-limit that can assist with this task:

npm install graphql-depth-limit

After you install it, you can add a validation rule to your GraphQL server configuration using the depthLimit function:

const depthLimit = require('graphql-depth-limit');

const server = new ApolloServer({
  typeDefs,
  resolvers,
  validationRules: [depthLimit(5)],
  context: async ({ req, connection }) => {}
});

Here, we have set the query depth limit to 10, which means that we provided our clients with the capability of writing queries that can go 10 selection sets deep. If they go any deeper, the GraphQL server will prevent the query from executing and return an error.

Limiting Query Complexity

Another measurement that can help you identify troublesome queries is query complexity. There are some client queries that might not run too deep but can still be expensive due to the amount of fields that are queried. Consider this query:

query everything($id: ID!) {
  totalUsers
  Photo(id: $id) {
    name
    url
  }
  allUsers {
    id
    name
    avatar
    postedPhotos {
      name
      url
    }
    inPhotos {
      name
      url
      taggedUsers {
        id
      }
    }
  }
}

The everything query does not exceed our query depth limit, but it’s still pretty expensive due to the number of fields that are being queried. Remember, each field maps to a resolver function that needs to be invoked.

Query complexity assigns a complexity value to each field and then totals the overall complexity of any query. You can set an overall limit that defines the maximum complexity available for any given query. When implementing query complexity you can identify your expensive resolvers and give those fields a higher complexity value.

There are several npm packages available to assist with the implementation of query complexity limits. Let’s take a look at how we could implement query complexity in our service using graphql-validation-complexity:

npm install graphql-validation-complexity

GraphQL validation complexity has a set of default rules out of the box for determining query complexity. It assigns a value of 1 to each scalar field. If that field is in a list, it multiplies the value by a factor of 10.

For example, let’s look at how graphql-validation-complexity would score the everything query:

query everything($id: ID!) {
  totalUsers # complexity 1
  Photo(id: $id) {
    name # complexity 1
    url # complexity 1
  }
  allUsers {
    id # complexity 10
    name # complexity 10
    avatar # complexity 10
    postedPhotos {
      name # complexity 100
      url # complexity 100
    }
    inPhotos {
      name # complexity 100
      url # complexity 100
      taggedUsers {
        id # complexity 1000
      }
    }
  }
}

By default, graphql-validation-complexity assigns each field a value. It multiplies that value by a factor of 10 for any list. In this example, totalUsers represents a sin‐ gle integer field and is assigned a complexity of 1. Querying fields in a single photo have the same value. Notice that the fields queried in the allUsers list are assigned a value of 10. This is because they are within a list. Every list field is multiplied by 10. So a list within a list is assigned a value of 100. Because taggedUsers is a list within the inPhotos list, which is within the allUsers list, the values of taggedUser fields is 10 × 10 × 10, or 1000.

We can prevent this particular query from executing by setting an overall query complexity limit of 1000:

const { createComplexityLimitRule } = require('graphql-validation-complexity');
const options = {
  validationRules: [
    depthLimit(5),
    createComplexityLimitRule(1000, {
      onCost: cost => console.log('query cost: ', cost)
    })
  ]
};

In this example, we set the maximum complexity limit to 1000 with the use of the createComplexityLimitRule found in the graphql-validation-complexity package. We’ve also implemented the onCost function, which will be invoked with the total cost of each query as soon as it is calculated. The preceding query would not be allowed to execute under these circumstances because it exceeds a maximum complexity of 1000.

Most query complexity packages allow you to set your own rules. We could change the complexity values assigned to scalars, objects, and lists with the graphql-validation-complexity package. It is also possible to set custom complexity values for any field that we deem very complicated or expensive.

There are other options for GraphQL security enhancements, of course, but these techniques will get you started thinking about how to block potentially malicious queries from jeopardizing your server.

Working with Query Arguments

Eve Porcello — Fri, 28 Feb 2020 01:47:34 +0000

A common refrain you'll hear about GraphQL is that you can make one request and get only the data you want. A query will return just the fields that you request, nothing more and nothing less. For example in the allLifts query, we make a selection for a certain set of fields:

query {
  allLifts {
    name
    status
  }
}

Note: To follow along with these queries, go to snowtooth.moonhighway.com.

There are several other fields that are part of the Lift type but not part of this query. We don't have to deal with them in the response though, because we're only requesting name and status.

Even though we're reducing the number of fields in the response, let's consider we only want to display one of these lifts in our UI. If you issued this query from the client, you'd get the full array of data back, and then it'd be the job of some JavaScript on the client to iterate over the array, find the right lift, and then display. Asking the client to transform that data is a lot of extra processing.

GraphQL allows you to move a lot of that logic to the GraphQL server. Instead of parsing, sorting, filtering on the client, you can do this work on the server, and then deliver the exact data that you need to the client.

Our UI only needs the one lift, right? So let's use one of the queries available on the API, the Lift query. To make this possible, we need to use query arguments. First, let's request a specific lift by id:

query {
  Lift(id: "panorama") {
    name
    status
  }
}

When we send this query, the GraphQL server will find the object in the lifts array that matches the id for panorama. Just the data that we need. If you look at the underlying schema, you'll notice that the id argument is non-nullable. We have to provide a value. But these types of filters can be optional, as we see in the allLifts query:

query {
  allLifts(status: OPEN) {
    name
    status
    capacity
  }
}

We can filter the results of the allLifts query by sending the optional status argument. This query will return only the open lifts.

Changing Data with Mutations

So far, we've talked about how to get data, but we haven't talked about you might change data with GraphQL. Queries are for getting data, mutations are for changing data. Just like with queries, the schema lists all of the possible mutation types that are available on the API. Mutations are defined like queries. They have names. They can have selection sets that return object types or scalars. The difference is that mutations perform some sort of a data change that affects the state of your backend data.

Writing a mutation starts with the mutation keyword. Then we'll nest the name of the mutation and any fields we want to return from the mutation, just like we did with the query:

mutation {
  setLiftStatus(id: "panorama", status: OPEN) {
    name
    status
    difficulty
  }
}

The setLiftStatus mutation takes in the id of the lift that we want to change and the new desired status of that lift. Then the setLiftStatus mutation returns the Lift object that has been changed. That way, we can view all of

Variables

We have changed data by sending new string values as mutation arguments. As an alternative, you can use input variables. Variables replace the static value in the query so that we can pass dynamic values instead. Let's consider our setLiftStatus mutation. Instead of dealing with strings, let's use variable names, which in GraphQL are always preceded by a $ character:

mutation ($id: ID! status: LiftStatus!) {
  setLiftStatus(id: $id, status: $status) {
    name
    status
    difficulty
  }
}

The static value is replaced by a $variable. Then, we state that the $variable can be accepted by the mutation. From there, we map each of the $variable names with the argument name. In GraphiQL or the Playground, there is a window for Query Variables. This is where we send the input data as a JSON object. Be sure to use the correct variable name as the JSON key:

{
  "id": "panorama",
  "status": "CLOSED"
}

One quick note here that when we pass an enum value inline with the query we don't use quotes around the value:

mutation {
  setLiftStatus(id: "panorama", status: OPEN) {
    name
    status
    difficulty
  }
}

It's OPEN not "open". When we pass the values as variables with JSON, we have to use valid JSON syntax and surround each word with doublequotes.

Variables are very useful when sending argument data. Not only will this keep our mutations more organized in a test, but allowing dynamic inputs will be hugely helpful later when connecting a client interface.

Default Values

It's also possible to supply a default value for a query or mutation argument. We'll construct the trailCount query to demonstrate:

query($status: TrailStatus!) {
  trailCount(status: $status)
}

The trailCount query takes in status as an argument. We're using query variables here too. But what happens if I don't supply a JSON variable value in the Query Variables panel? We'll get an error: Response not successful: Received status code 400. To resolve this, we could just update the JSON panel, or we could provide a default value for status using an equals sign:

query($status: TrailStatus = OPEN) {
  trailCount(status: $status)
}

Note that you'll need to remove the exclamation point from TrailStatus. By setting TrailStatus to OPEN, this means that there will never be a case where we supply null. Instead, if we don't supply a value, the mutation will execute using the default value.

Understanding GraphQL Schemas

Eve Porcello — Mon, 17 Feb 2020 20:44:28 +0000

When you start working with GraphQL, you'll start to realize that GraphQL is going to change your design process. Instead of looking at your APIs as a collection of REST endpoints, you'll start looking at APIs as collections of types. Before breaking ground on your new API, you need to think about, talk about, and formally define the data types that your API will expose. This collection of types is called a schema.

GraphQL comes with a language that we can use to define our schemas called the Schema Definition Language, or SDL. Just like the GraphQL Query Language, the GraphQL SDL is the same no matter what language or framework you use to construct your applications. GraphQL schema documents are text documents that define the types available in an application, and they are later used by both clients and servers to validate GraphQL requests.

Since we're already familiar with how to write queries for the Snowtooth API, let's take a closer look at the underlying schema that makes those queries possible.

Creating Schema Types

A GraphQL API has a certain list of queries that are available on the API. One such query is liftCount:

Query Language

query {
  liftCount
}

The Query type has a specific meaning: it's the type that contains all of the queries that we can send to this API. liftCount and all other available queries are represented in the schema in the Query type:

Schema Definition Language

type Query {
  liftCount: Int!
}

The liftCount query returns a scalar type. Think of a scalar type as being a single value, not an object. There are five built-in scalars that are part of the schema definition language:

String: A UTF-8 character sequence
Int: A 32-bit integer
Float: A floating point value
Boolean: true or false
ID: A unique identifier that is serialized as a String

We will use these scalars anytime we want to return a single value from a field. We can also create our own custom objects called types.

The core unit of any GraphQL schema is the type. The Snowtooth API has two main types: a Lift and a Trail. A type has fields that represent the data associated with each object. Each field returns a specific type of data.

Let's begin by defining the fields that are part of the Lift type:

type Lift {
  id: ID!
  name: String!
  status: String
  capacity: Int!
  night: Boolean!
  elevationGain: Int!
}

We have created our first GraphQL object type: a Lift. Between the curly brackets, we've defined the lift's fields. Each of these fields returns one of GraphQL's scalar types.

So, what's the deal with the exclamation point?

type Lift {
  id: ID! # can't return null (non-nullable)
  name: String! # can't return null (non-nullable)
  status: String # can return null (nullable)
  ...
}

The exclamation point after a value means that this is non-nullable. If we query the id or name field, the value returned must not be null. If there is no exclamation point like with the status field, then it's ok to return null from that field.

As you work to define your schema, you'll continue to create a type for each of your domain objects. Let's go ahead and create a Trail in the schema:

type Trail {
  id: ID!
  name: String!
  status: String
  difficulty: String!
  groomed: Boolean!
  trees: Boolean!
  night: Boolean!
}

Now that we've created our two custom object types, we want to write a couple of queries that will return that data.

Returning Lists

Let's construct another query with the query language that will return all of the lifts on the mountain:

query {
  allLifts {
    name
    status
  }
}

This query returns a list of lift objects. So how would we construct the schema to support this query? We already have the Lift object, so instead of returning a scalar value from the query, we're going to return a list of objects. The schema should look like this:

type Query {
  liftCount: Int!
  allLifts: [Lift!]!
}

The allLifts query returns a list of Lift objects. The exclamation points here mean that the allLifts query cannot return null, and no value within the lifts array can be null. The query could return an empty array though and not cause any errors, because nothing is null about an empty array.

Similarly, we can add an allTrails query to return a list of trails:

type Query {
  liftCount: Int!
  allLifts: [Lift!]!
  allTrails: [Trail!]!
}

The nullability rules are the same here for the Trail type.

Enums

Another type that we can use in the schema definition language is an enum. Enums, or enumeration types, are scalar types that allow a field to return a restricted list of values. When you want to make sure that a field returns one value from a limited set of values, use an enum.

One place where we could improve our schema is in the Lift type, specifically the status field:

type Lift {
  ...
  status: String
  ...
}

Right now, the status field can return any string, but there are only three possible lift statuses that should be returned here: OPEN, CLOSED, and HOLD. We can create an enum and set the value of the enum to the status field in order to be more restrictive of the options:

enum LiftStatus {
  OPEN
  CLOSED
  HOLD
}

type Lift {
  ...
  status: LiftStatus
  ...
}

Now we've limited the options for this field. Notice that the enum values are capitalized. This is a convention, not a rule.

We can repeat this for the Trail type, adding a TrailStatus enum. In this case, we'll only allow OPEN and CLOSED as values for TrailStatus:

enum TrailStatus {
  OPEN
  CLOSED
}

type Trail {
  ...
  status: TrailStatus
  ...
}

Arguments

Currently, our schema has a few different queries listed in the Query type:

type Query {
  liftCount: Int!
  allLifts: [Lift!]!
  allTrails: [Trail!]!
}

There might be a time when we want to query an individual lift or an individual trail. To do this, we'll need to take advantage of query arguments. Arguments can be added to any field in GraphQL. They allow us to send data that will affect the outcome of our GraphQL operations. Let's create a query called Lift that will return a lift by id.

type Query {
  ...
  Lift(id: ID!): Lift!
}

Now if we pass the id of one of the lifts, we should filter the results to the single Lift object that matches that id. Keep in mind that we're not worried about implementation details at this moment. Right now, we're only concerned about creating the blueprint for these data relationships.

Similarly, we can create a Trail query to return a trail by id. It's going to look pretty similar to the Lift query:

type Query {
  ...
  Lift(id: ID!): Lift!
  Trail(id: ID!): Trail!
}

Connected Data

It's possible to return data about different types in a single query. Making connections between data points is one of the most powerful features of GraphQL. At Snowtooth Mountain, a lift transports people to a certain list of trails, and a trail can be accessed by taking one or more of these lifts.

If we want to replicate this data relationship with our GraphQL schema, we need to connect these two data types. First, we'll connect a Lift to a Trail:

type Lift {
  ...
  trailAccess: [Trail!]!
}

When we query the trailAccess field, this will return a list of all of the trails that are accessed by this lift.

To draw the line back to the Lift from the Trail, we can add another field to the Trail type that returns a list of lifts.

type Trail {
  ...
  accessedByLifts: [Lift!]!
}

Connecting data doesn't always mean returning a list. Keep in mind that you can return a single object from a field as well. Perhaps our Trail had a namedAfter field to describe the Person who the Trail is named after. In the schema, this would look like this:

type Trail {
  ...
  namedAfter: Person!
}

The schema design process is vitally important to the success of a GraphQL project, but we think it's one of most fun parts. The schema document is the contract between engineers from all over the stack and provides a common vocabulary about the types that are part of the project.

Understanding the GraphQL Query Language

Eve Porcello — Thu, 06 Feb 2020 00:34:07 +0000

When Facebook open-sourced GraphQL, it had a few different parts. It came with a spec. That specification document described all of the features of the GraphQL query language and the schema definition language. It also came with a reference implementation of a GraphQL server called graphql.js. This was an example of what a GraphQL server might look like so that other people could implement their own servers in a variety of languages.

The spec gave us rules. The reference implementation gave us direction. But a third piece, GraphiQL, gave us access, and access is how you create a legion of fans.

GraphiQL is an in-browser IDE that allows you to explore GraphQL APIs. No setup required. GraphiQL allows you to experiment with the query language, the QL part of GraphQL, which is at the heart of anything you’ll do with GraphQL in any implementation.

The query language is standardized according to the spec. It doesn’t matter what language you are using: a GraphQL query is a GraphQL query. The query syntax is a string that looks the same regardless of whether the project uses JavaScript, Java, Haskell, or anything else.

To demonstrate some of the features of the query language, we're going to use the Snowtooth API, a real GraphQL API for a fake ski resort. The API uses GraphQL Playground, a similar tool to GraphiQL, that will allow you to send these queries and receive some data right in the browser.

When you visit the Snowtooth API in the center, you'll see the GraphQL endpoint: https://snowtooth.moonhighway.com, and we'll send GraphQL queries to this endpoint. With GraphQL, there is only one endpoint.

When we want to request some data from an API, we'll use a query. When you send a query, you ask for units of data by field. These fields map to the same field in the JSON data response you receive from your server. For example, if you send a query for allLifts and request the name and status fields, you should receive a JSON response that contains an array for allLifts and a string for each lift’s name and each lift’s status, as demonstrated here:

query {
  allLifts {
    name
    status
  }
}

Add this query to the left side of the screen. Click the Play button, and you'll see the JSON response on the right. Notice when you send the query, all of the fields in the query match the fields in the response.

The query keyword is called the operation name. This describes what type of query or operation that is being sent to the GraphQL service. Nested inside the curly braces are fields. A field returns some data. Any fields nested inside of curly braces are called a selection set.

You can add multiple queries to a query document, but you can run only one operation at a time. For example, you could place two query operations in a query document:

query {
  allLifts {
    name
    status
  }
}
query {
  allTrails {
    name
    difficulty
  }
}

If you tried to run one of these queries though, you'd see an error. If you have more than one query in a query document, you have to give the query an operation name. Think of an operation name like a function name.

query lifts {
  allLifts {
    name
    status
  }
}
query trails {
  allTrails {
    name
    difficulty
  }
}

When you press the Play button, a dropdown will appear to prompt you to select one of these two operations. If you want to send one request for all of this data, you can place it all within the same query:

query liftsAndTrails {
  allLifts {
    name
    status
  }
  allTrails {
    name
    difficulty
  }
}

Here is where the benefits of GraphQL begin to crystallize. We are able to receive all kinds of different datapoints in a single query. We are also asking for the name and status of every lift. Finally, we ask for the name and difficulty of every trail in the same query.

Connections

In a GraphQL query, a field can return either scalar types or object types. Scalar types are similar to primitives in other languages. They are the leaves of our selection sets and return a single value. Out of the box, GraphQL comes with five built-in scalar types: integers (Int), floats (Float), strings (String), booleans (Boolean), and unique identifiers (ID).

Both integers and floats return JSON numbers, and String and ID return JSON strings. Booleans return Booleans. Even though ID and String will return the same type of JSON data, GraphQL still makes sure that IDs return unique strings.

GraphQL object types are groups of one or more fields that you define in your schema. They define the shape of the JSON object that should be returned. JSON can endlessly nest objects under fields and so can GraphQL. We can connect objects together by querying one object for details about related objects.

For example, suppose that we want to return data about the trails that are accessed by each lift:

query {
  allLifts {
    name
    capacity
    trailAccess {
      name
    }
  }
}

In this query, we are asking for data about all of the lifts and then all of the trails you can access off of each lift. Our selection set includes a request for the capacity field. Capacity is a scalar type; it returns an integer that represents the number of people that can ride on one chair. The trailAccess field is of type Trail (an object type). In this example, trailAccess returns a filtered list of trails that are accessible from each lift.

This example operation queries a one-to-many connection between two types of data, lifts and trails. One lift is connected to many related trials.

The same relationship exists from Trail to Lift. The connection is created on the accessedByLifts field. When you query that field, you return the lift or lifts that you would have to take to get to the trail.

query AllTrails {
  allTrails {
    name
    accessedByLifts {
      name
    }
  }
}

For a deeper look at the GraphQL Query Language, check out Eve's Query Language course on egghead.io.

Understanding Fragments in GraphQL

Eve Porcello — Fri, 04 Oct 2019 14:33:58 +0000

This was originally posted on the Moon Highway blog.

The "QL" in GraphQL stands for the query language, and a key, yet often overlooked feature of the language is GraphQL fragments. A GraphQL query document can contain definitions for operations and fragments. Fragments are selection sets that can be reused in multiple operations.

Let's use the Snowtooth API, a fake ski resort with a real GraphQL API, to send some new queries:

query {
  Lift(id: "jazz-cat") {
    name
    status
    capacity
    night
    elevationGain
    trailAccess {
      name
      difficulty
    }
  }
  Trail(id: "river-run") {
    name
    difficulty
    accessedByLifts {
      name
      status
      capacity
      night
      elevationGain
    }
  }
}

This query requests information about the Jazz Cat lift and the River Run trail. The Lift includes name, status, capacity, night, and elevationGain in its selection set. The information that we want to obtain about the River Run trail includes a sub-selection on the Lift type for the same fields. We could create a fragment that can help us reduce redundancy in our query:

fragment liftInfo on Lift {
 name
 status
 capacity
 night
 elevationGain
}

You create fragments by using the fragment identifier. Fragments are selection sets on specific types, so you must include the type that is associated with each fragment in its definition. The fragment in this example is named liftInfo, and it is a selection set on the Lift type. When we want to add the liftInfo fragment fields to another selection set, we can do so by using three dots with the fragment name:

query {
  Lift(id: "jazz-cat") {
    ...liftInfo
    trailAccess {
      name
      difficulty
    }
  }
  Trail(id: "river-run") {
    name
    difficulty
    accessedByLifts {
      ...liftInfo
    }
  }
}

The syntax is similar to the JavaScript spread operator, which is used for a similar purpose: to assign the keys and values of one object to another. These three dots instruct GraphQL to assign the fields from the fragment to the current selection set.

In this example, we are able to select the name, status, capacity, night, and elevationGain in two different places within our query using one fragment. We would not be able to add the liftInfo fragment to the Trail selection set because it defines only fields on the Lift type. We can add another fragment for trails:

query {
  Lift(id: "jazz-cat") {
    ...liftInfo
    trailAccess {
      ...trailInfo
    }
  }

  Trail(id: "river-run") {
    ...trailInfo
    groomed
    trees
    night
  }
}

fragment trailInfo on Trail {
  name
  difficulty
  accessedByLifts {
    ...liftInfo
  }
}

fragment liftInfo on Lift {
  name
  status
  capacity
  night
  elevationGain
}

Here, we have created a fragment called trailInfo and used it in two places within our query. We’re also using the liftInfo fragment in the trailInfo fragment to select details about the connected lifts. You can create as many fragments as you want and use them interchangeably. In the selection set used by the River Run trail query, we are combining our fragment with additional details that we want to select about the River Run trail. You can use fragments in combination with other fields in a selection set. You also can combine multiple fragments on the same type in a single selection set:

query {
  allTrails {
    ...trailStatus
    ...trailDetails
  }
}

fragment trailStatus on Trail {
  name
  status
}

fragment trailDetails on Trail {
  groomed
  trees
  night
}

Another nice thing about fragments is that you can modify the selection sets used in many different queries simply by modifying one fragment:

fragment liftInfo on Lift {
 name
 status
}

This change to the selection set in the liftInfo fragment causes every query that is using this fragment to select less data. Fragments are a pretty slick feature of the GraphQL query language. Consider how you might refactor your current queries to include these compositional helpers.

If you haven't checked out my Query Language course yet on egghead.io, it covers fragments and many other features of the query language!

Improving Code with useReducer

Eve Porcello — Thu, 26 Sep 2019 15:06:43 +0000

The next in our series of articles from the Second Edition of Learning React is about useReducer.

Consider the Checkbox component. This component is a perfect example of a component that holds simple state. The box is either checked or not checked. checked is the state value, and setChecked is a function that will be used to change the state. When the component first renders, the value of checked will be false:

function Checkbox() {
  const [checked, setChecked] = useState(false);

  return (
    <>
      <input
        type="checkbox"
        value={checked}
        onChange={() => setChecked(checked => !checked)}
      />
      {checked ? "checked" : "not checked"}
    </>
  );
}

This works well, but one area of this function could be cause for alarm:

onChange={() => setChecked(checked => !checked)}

Look at it closely. It feels ok at first glance, but are we stirring up trouble here? We're sending a function that takes in the current value of checked and returns the opposite, !checked. This is probably more complex than it needs to be. Developers could easily send the wrong information and break the whole thing. Instead of handling this way, why not provide a function as a toggle?

Let's add a function called toggle that will do the same thing: call setChecked and return the opposite of the current value of checked:

function Checkbox() {
  const [checked, setChecked] = useState(false);

  function toggle() {
    setChecked(checked => !checked);
  }

  return (
    <>
      <input type="checkbox" value={checked} onChange={toggle} />
      {checked ? "checked" : "not checked"}
    </>
  );
}

This is better. onChange is set to a predictable value: the toggle function. We know what that function is going to do every time, everywhere it is used. We can still take this one step further to yield even more predictable results each time we use the checkbox component. Remember the function that we sent to setChecked in the toggle function?

setChecked(checked => !checked);

We're going to refer to this function, checked => !checked, by a different name now: a reducer. A reducer function's most simple definition is that it takes in the current state and returns a new state. If checked is false, it should return the opposite, true. Instead of hardcoding this behavior into onChange events, we can abstract the logic into a reducer function that will always produce the same results. Instead of useState in the component, we'll use useReducer:

function Checkbox() {
  const [checked, toggle] = useReducer(checked => !checked, false);

  return (
    <>
      <input type="checkbox" value={checked} onChange={toggle} />
      {checked ? "checked" : "not checked"}
    </>
  );
}

useReducer takes in the reducer function and the initial state, false. Then we'll set the onChange function to toggle which will call the reducer function.

Our earlier reducer checked => !checked is a prime example of this. If the same input is provided to a function, the same output should be expected. This concept originates with Array.reduce in JavaScript. reduce fundamentally does the same thing as a reducer: it takes in a function (to reduce all of the values into a single value) and an initial value and returns one value.

Array.reduce takes in a reducer function and an initial value. For each value in the numbers array, the reducer is called until one value is returned.

const numbers = [28, 34, 67, 68];

numbers.reduce((number, nextNumber) => number + nextNumber, 0); // 197

The reducer sent to Array.reduce takes in two arguments. You can also send multiple arguments to a reducer function:

function Numbers() {
  const [number, setNumber] = useReducer(
    (number, newNumber) => number + newNumber,
    0
  );

  return <h1 onClick={() => setNumber(30)}>{number}</h1>;
}

Every time we click on the h1, we'll add 30 to the total each time.

useReducer to Handle Complex State

useReducer can help us handle state updates more predictably as state becomes more complex. Consider an object that contains user data:

const firstUser = {
  id: "0391-3233-3201",
  firstName: "Bill",
  lastName: "Wilson",
  city: "Missoula",
  state: "Montana",
  email: "bwilson@mtnwilsons.com",
  admin: false
};

Then we have a component called User that sets the firstUser as the initial state, and the component displays the appropriate data:

function User() {
  const [user, setUser] = useState(firstUser);

  return (
    <div>
      <h1>
        {user.firstName} {user.lastName} - {user.admin ? "Admin" : "User"}
      </h1>
      <p>Email: {user.email}</p>
      <p>
        Location: {user.city}, {user.state}
      </p>
      <button>Make Admin</button>
    </div>
  );
}

A common error when managing state is to overwrite the state:

<button
  onClick={() => {
    setUser({ admin: true });
  }}
>
  Make Admin
</button>

Doing this would overwrite state from firstUser and replace it with just what we sent to the setUser function: {admin: true}. This can be fixed by spreading the current values from user, and then overwriting the admin value:

<button
  onClick={() => {
    setUser({ ...user, admin: true });
  }}
>
  Make Admin
</button>

This will take the initial state and push in the new key/values: {admin: true}. We need to rewrite this logic in every onClick, making it prone to error. I might forget to do this when I come back to the app tomorrow.

function User() {
  const [user, setUser] = useReducer(
    (user, newDetails) => ({ ...user, ...newDetails }),
    firstUser
  );
  ...
}

Then send the new state value newDetails to the reducer, and it will be pushed into the object:

<button
  onClick={() => {
    setUser({ admin: true });
  }}
>
  Make Admin
</button>

This pattern is useful when state has multiple sub-values or when the next state depends on a previous state. Here we're tapping in to the power of the spread. Teach everyone to spread, they'll spread for a day. Teach everyone to useReducer, and they'll spread for life.

Getting Familiar with useEffect: Part One

Eve Porcello — Wed, 18 Sep 2019 22:12:58 +0000

This article was originally posted on MoonHighway.com.

Rendering is the heartbeat of a React application. When something changes (props, state), the component tree re-renders, reflecting that change in the user interface. But what happens when we need to do something after a render? As you might imagine, there's a Hook for that.

Consider a simple component, the Checkbox. We're using useState to set a checked value and a function to change the value of checked called setChecked. A user can check and uncheck the box, but how might we alert the user that the box has been checked? We'll try this with an alert as it is a great way to block the thread:

function Checkbox() {
  const [checked, setChecked] = useState(false);

  alert(`checked: ${checked.toString()}`);

  return (
    <>
      <input
        type="checkbox"
        value={checked}
        onChange={() => setChecked(checked => !checked)}
      />
      {checked ? "checked" : "not checked"}
    </>
  );
}

We've added the alert before the render to block the render. The component will not render until the user clicks the OK button on the alert box. Because the alert is blocking, we don't see the next state of the checkbox rendered until clicking OK.

That isn't the goal, so maybe we should place the alert after the return?

function Checkbox() {
  const [checked, setChecked] = useState(false);

  return (
    <>
      <input
        type="checkbox"
        value={checked}
        onChange={() => setChecked(checked => !checked)}
      />
      {checked ? "checked" : "not checked"}
    </>
  );

  alert(`checked: ${checked.toString()}`);
}

Scratch that. We can't call alert after the render because the code will never be reached. To ensure that we see the alert as expected, we can use useEffect. Placing the alert inside of the useEffect function means that the function will be called after the render, as a side effect:

function Checkbox() {
  const [checked, setChecked] = useState(false);

  useEffect(() => {
    alert(`checked: ${checked.toString()}`);
  });

  return (
    <>
      <input
        type="checkbox"
        value={checked}
        onChange={() => setChecked(checked => !checked)}
      />
      {checked ? "checked" : "not checked"}
    </>
  );
}

We use useEffect when a render needs to cause side effects. Think of a side effect as something that a function does that isn't part of the return. The function is the Checkbox. The Checkbox function returns a fragment. But we might want the component to do more than that. Those things we want the component to do other than return UI are called effects.

An alert, a console.log, or an interaction with a browser or native API is not part of the render. It's not part of the return. In a React app though, the render affects the results of one of these events. We can use useEffect to wait for the render, and then provide the values to an alert or a console.log:

useEffect(() => {
  console.log(checked ? "Yes, checked" : "No, not checked");
});

Similarly, we could check in with the value of checked on render and then set that to a value in localStorage:

useEffect(() => {
  localStorage.setItem("checkbox-value", checked);
});

We also might use useEffect to focus on a specific text input that has been added to the DOM. React will render the output, and then call useEffect to focus the element:

useEffect(() => {
  txtInputRef.current.focus();
});

On render, the txtInputRef will have a value. We can access that value in the effect to apply the focus. Every time we render, useEffect has access to the latest values from that render: props, state, refs, etc.

Cool, but... why? Think about a render. We render a checkbox where the checked value is false. On that render, React will look at the value of checked and call useEffect:

useEffect(() => {
  console.log(checked ? "Yes, checked" : "No, not checked");
});

React is calling this function post-render:

useEffect(() => console.log("No, not checked"));

Then we update the checked value to true. This causes another render. At this point, the render will lead to useEffect being called again but at this point the function is different:

useEffect(() => console.log("Yes, checked"));

Every time the component renders, we can see the value of checked in useEffect because useEffect is a unique function every time. Think of useEffect as being a function that happens after a render. When a render fires, we can take a look at that render's values and use them in the effect. Then once we render again, the whole thing starts over. New values, then new renders, then new effects.

useEffect is a powerful tool to understand when building a React application. In the next part of this series, we'll take a closer look at the dependency array that allows us to define more specific rules around why and when rendering should happen.

Using Netlify Dev with Apollo Server Lambda: An Appreciation

Eve Porcello — Wed, 31 Jul 2019 15:50:54 +0000

A little over a year ago, we needed to publish the GraphQL Workshop website and decided to use Netlify for hosting. Before we could deploy the site, I needed to set up the security certificate to enable HTTPS. Pre-Netlify, this used to take forever, so I carved out some time on the calendar. I then promptly found a one-click option to secure the site with HTTPS, and the whole thing was done automatically in around 37 seconds. Oh, and it was free.

Ever since that day, I've been a Netlify believer, but I've always thought of Netlify as a hosting provider for front-end sites, not for standing up GraphQL servers. As it turns out, I was just as wrong about that as I was about how long it would take take to deploy a secure website with Netlify. You 100% can use Netlify to do this. Let's take a closer look at some of the tools that will help us make this happen:

Netlify Dev

Announced in April 2019, Netlify Dev is a command line tool that allows you to run Netlify's platform on your computer. This allows you to test your site locally (i.e. Create React App) with serverless functions that handle specific tasks like running your GraphQL server that you created with Apollo Server. Netlify Dev also gives you some starter kits for common tasks as you'll see in our example below.

Netlify Functions

Netlify Functions allow you to deploy server-side code (your GraphQL API) to AWS without an AWS account alongside your frontend. That means you don't have to set up different repositories for front-end and back-end. Everything can run from the same project, on the same platform. Also, Netlify has the beloved deploy preview feature, so that when you send a pull request, you can test the preview to make sure both the front and backends are working as expected.

Apollo Server Lambda

We've talked about how to set up the default Apollo Server in the article, Building a GraphQL Server in Five Minutes. Apollo Server Lambda is the variation of this server that allows you to deploy the server using a Lambda function.

Create React App

Create React App allows you to generate a React project, and we'll use this as the starter kit for the deploy.

Now that we're acquainted with the pieces, let's get started.

1. Create a React Project

Use npx to generate the files for a React project:

npx create-react-app netlify-apollo
cd netlify-apollo

2. Install Netlify CLI Globally

We'll need the Netlify CLI to use Netlify Dev. If you're on a Mac, install it globally:

npm install netlify-cli -g

On a PC, open the command prompt as an administrator and run:

npm install netlify-cli

3. Run the Netlify Dev Command

Since you're currently located in the netlify-apollo folder, you can run the Netlify Dev command. When you run this command, Netlify uses a project detector to determine which type of project is in the folder (Create React App? Gatsby? Hugo?). Then it will run the development server and any functions that you create within the project. This mimics how your application will work in production so you can test locally with minimal configuration.

netlify dev

Netlify will detect that we're using Create React App and will run our server on localhost:3000, the default port for Create React App, and localhost:8888, Netlify's default port.

4. Add netlify.toml

This is a configuration file for Netlify. You'll describe where your Netlify functions should be placed when you create them.

[build]
  functions = "src/functions" 
  publish = "build"

5. Create the Netlify Function

This is the command that's used to create a Netlify function.

netlify function:create

This will give you a prompt to pick the starter template you'd like to use using the arrow keys. There are many here: node-fetch, google-analytics, hello-world, etc. We want to use the apollo-graphql one. Hit the down arrow until you've selected that and hit enter. This will install all of the dependencies for the project plus give you a server template where you can get started creating your own GraphQL server with your own types.

Then you'll be prompted to name the function. We can stick with the default: apollo-graphql.

Now you can check out the src folder. Here you'll find a new folder called functions with a subfolder called apollo-graphql. In the apollo-graphql.js file, you'll see a starter GraphQL server for author data. Here you can replace this with the types and queries that you want to make available on your service.

6. Run Netlify Dev to Test the Server

We'll want to see our app running, so we'll run the Netlify command again:

netlify dev

When you visit localhost:8888, you'll see the default Create React App running. To view the GraphQL Playground, you can head over to http://localhost:8888/.netlify/functions/apollo-graphql. There you'll see it running, and you can send a test query to make sure that everything is working as expected.

query {
  allAuthors {
    name
  }
}

There we go! We have scaffolded the front and the backend for a project that uses GraphQL and React. The next steps will be to adjust the schema and resolvers.

Netlify Dev and Apollo Server Lambda are a great pair for building GraphQL APIs quickly. In a future article, we'll discuss how you can use Apollo Client to display data provided by your GraphQL API in your frontend React application.

If you want to learn more about any of these tools, I'd recommend any of the following resources:

Netlify Dev Documentation: The place to start.
Announcing Netlify Dev - video: This is the Netlify Dev announcement that Matt Biilmann gave at JAMstack Conf in April
Serverless GraphQL with Netlify Dev - video: This is a great talk by Shawn Wang from Apollo Day in May 2019.

A Quick Intro to Apollo Client

Eve Porcello — Sat, 20 Jul 2019 18:05:41 +0000

A few months ago, we posted an article about how to fetch data from a GraphQL API. In it, we looked at the Snowtooth API, a fake ski resort with a real GraphQL API, and we were able to send queries to get data and send mutations to change data. We all had a great time.

Now that a few months have passed, our hair is a little longer. Our beard a bit more full. And now we might be thinking: is it time to incorporate Apollo Client? Or more importantly, why might you want to incorporate Apollo Client?

Apollo Client handles network requests and efficient caching. It will handle the network interface with the GraphQL API by creating a link. The cache will save queries and their resulting objects. A huge benefit of using REST is the ease with which you can handle caching. With REST, you can save the response data from a request in a cache under the URL that was used to access that request. For example, if Snowtooth was a REST API, you'd go to the lifts route, /lifts, to get lift data, and then you'd cache the data at under that URL.

With GraphQL, we're dealing with a single endpoint, so having a localized caching solution is essential as we build fast, efficient apps. We could create our own cache, but leaning on the vetted Apollo Client is a great place to get started.

Apollo Client Setup

Let's create a simple Apollo Client that will get data from the Snowtooth API.

Then, we'll set up the project using Create React App. Using React isn't required for working with Apollo Client, but running this will generate a project shell for us that might be useful when extending this into a real application.

Start by running this command in the Terminal or Command Prompt:

npx create-react-app snowtooth-client

npx will execute the create-react-app command with the name of the project, in this case, snowtooth-client. Then make sure you're in the snowtooth-client directory and start the app:

cd snowtooth-client
npm start

This will run the starter app on localhost:3000. Next, we'll install some dependencies:

npm i apollo-client graphql

All of the changes we'll make to our mini app will happen in the src/index.js file. The first change is that we'll highlight everything in the file and delete it. Then we'll create the client and log whatever the client is to the console:

import { ApolloClient } from "apollo-client";

const client = new ApolloClient();

console.log(client);

At this point, we should be seeing an error: Uncaught TypeError: Cannot read property 'cache' of undefined. Remember earlier that we said that Apollo Client gives us two things: the link to the GraphQL data and the cache? Well, those are the two things that need to be provided to the client constructor when setting it up. Start by installing a few more helpful packages:

npm i apollo-link-http apollo-cache-inmemory

These packages are going to help us connect to our GraphQL API and set up a local cache. Once installed, we'll import and use them in the index.js file. Let's start with the imports:

import { createHttpLink } from "apollo-link-http";
import { InMemoryCache } from "apollo-cache-inmemory";

Then we'll use these helpers in the client constructor:

const client = new ApolloClient({
  link: createHttpLink({ uri: "https://snowtooth.moonhighway.com" }),
  cache: new InMemoryCache()
});

createHttpLink takes in an object with our GraphQL API provided on the uri key and will fetch GraphQL results from a GraphQL API over an http connection. InMemoryCache is the default cache implementation for Apollo Client 2.0.

We can check out localhost:3000 again and open the console. This is now logging the client. There's not too much here yet, but we can see some familiar values here like the cache and link.

At this point, we're not sending a request though. In order to send a request (a query) to the GraphQL endpoint, we'll need to incorporate one last package: graphql-tag.

npm install graphql-tag

Once installed, we'll import a function called gql from graphql-tag and wrap the query that we want to send to the API in this tag:

import gql from "graphql-tag";

const query = gql`
  query {
    allLifts {
      name
    }
  }
`;

The tag function gql that wraps the query will parse the query string and turn it into an AST, an abstract syntax tree. An AST is a representation of the query string as an object. Once defined, we'll use the client.query function to send a query to the GraphQL API:

client
  .query({
    query
  })
  .then(console.log);

Calling client.query will send the query to the API that is defined in our client instantiation. Once you run this, you should see the JSON response logged to the console:

This object gives us all of the data from the query on the key called data. We also see whether the data is loading, if the request is stale, and the network status code. If successful, the network status code will be 7.

Another thing we can take a look at with a console log message is the cache:

console.log("Cache", client.cache);

This will show the entire client cache object. We can drill down into the data response as well with:

console.log("Cache", client.extract());

The data is cached on a key called ROOT_QUERY. Then we see the data added to an index on the query value. For example, if we ask for allLifts, the first lift will be cached at allLifts.0, the second lift cached at allLifts.1, and so on.

If you want to be able to view the state of the cache in a nicer user interface, I'd recommend installing the Apollo Dev Tools Chrome Extension. Any time you're on a page that is using Apollo Client, you'll be able to open the Dev Tools This will give you visibility into the cache which is a little nicer than logging these details to the console:

The fact that you can see the state of the cache is cool, but it's also really useful to have the GraphiQL explorer available. If the page you're viewing has an instance of the Apollo Client, you'll be able to use GraphiQL to introspect the schema and send queries, mutations, and subscriptions. Killer.

Apollo Client doesn't require you to use any sort of specific UI library. Everything we've done in this article has used good old vanilla JavaScript. If you want to learn more about how to integrate Apollo Client with React though, check out our other article on Apollo React Hooks!

GitHub Authorization with GraphQL and Apollo Server

Eve Porcello — Sat, 22 Jun 2019 19:57:07 +0000

This article was originally posted on the Moon Highway.

Authorizing and authenticating users is an important part of building web applications. We need to know who the users are and what they are allowed to see. With a GraphQL app, how do we make sure that a user is allowed to see content? We need to authenticate them to make sure that we identify them. We also need to authorize them to prove that they have the right to access the application.

There are a number of strategies that can be used to authenticate and authorize users. In this article, we'll take a closer look at how to handle authorization with GitHub. We'll lean on GitHub to provide the account details, and we'll be able to use GitHub credentials for each user who attempts to log in.

Setting Up GitHub OAuth

The first step of setting up GitHub authorization is to set up a GitHub app. The steps to do this are as follows:

Go to https://www.github.com and log in.
Go to Settings.
Go to Developer Settings.
Select OAuth Apps from the left navigation.
Select New Oauth App.
Add These Settings:
- Application name: Localhost 3000
- Homepage URL: http://localhost:3000
- Application description: A test application for authorizing a user with GitHub
- Authorization callback url: http://localhost:3000
Click Register Application.
Copy the Client ID and Client Secret from the account page.

Your GitHub app is all set up! Now you'll copy and paste the Client ID and Client Secret into a new file at the root of your project called .env. It should look like this with your own variables provided:

CLIENT_ID=<Your_Client_ID_Here>
CLIENT_SECRET=<Your_Client_Secret_Here>

The Authorization Process

Now that our app is set up with GitHub, it's time to incorporate the authorization and authentication process into our GraphQL application. We'll send a request to GitHub via a URL that contains the GitHub Client ID to ask the user to allow access to their GitHub account. Then we'll take the response code and pass it back to GitHub to obtain a token. The token basically says "Ok, this user is allowed to use the app." They are authenticated, and they are authorized.

We will build and test all of these steps, but the basic process boils down to the following:

Client: Asks GitHub for a code using a url with a client_id.
User: Allows access to account info on GitHub for client application
GitHub: Sends code to OAuth redirect url: http://localhost:3000?code=XYZ
Client: Sends GraphQL Mutation authorizeWithGithub(code) with code
API: Requests a GitHub access_token with credentials: client_id, client_secret, and client_code
GitHub: Responds with access_token that can be used with future info requests
API: Request user info with access_token
GitHub: Responds with user info: name, githubLogin, avatar

To set this up on the server, we'll need to create two queries and one mutation:

A query to get the GitHub login url (which will give us the code): githubLoginUrl.
A mutation to authorize the user with GitHub: authorizeWithGithub
A query to return the currently logged in user: me.

Step One: Create the `githubLoginUrl` Query

To authorize a user, I need to send my CLIENT_ID to GitHub. Once they recognize the Client ID, they'll let me authorize the app using my GitHub username and password. The URL I need to paste into my browser looks like this:

https://github.com/login/oauth/authorize?client_id=${Client-ID-here}&scope=user

Wouldn't it be cool if instead of typing this from memory I could send a query that returns that URL? So I can just copy and paste it into the browser? Yes, that would be extremely cool, so let's set that up in our schema. When I send the githubLoginUrl query, it should return the URL string:

type Query {
  githubLoginUrl: String!
}

Now we need to write the resolver that will construct that URL for us. We have the structure for the link (https://github.com/login/oauth/authorize?client_id=${Client-ID-here}&scope=user), so all we need to do is provide the CLIENT_ID from the environment variables using a template string:

Query: {
  githubLoginUrl: () =>
    `https://github.com/login/oauth/authorize?client_id=${
      process.env.CLIENT_ID
    }&scope=user`;
}

When I send the githubLoginUrl query, I receive back a string that can be easily pasted into the browser. The query will look like this:

query {
  githubLoginUrl
}

And will return:

{
  "data": {
    "githubLoginUrl": "https://github.com/login/oauth/authorize?client_id=YOUR-UNIQUE-CLIENT-ID&scope=user"
  }
}

When I visit this URL, the GitHub app in the browser will ask me to allow this app to have access to my GitHub account details. Next, I'll authorize the app and enter my password. Once I authorize the app, a new URL will be present in the URL bar. Then I will grab the code from the end of the URL string:

http://localhost:3000/?code=<YOUR-UNIQUE-CODE>

We'll hang on to this code for now because we'll need to send this back to GitHub to request a token. This process is pretty manual, but later when we build a client application, we'll handle all of this via UI elements. In other words, when I click a login button, all of this will happen behind the scenes. For now, this is a great way to test that the auth process is working.

Step Two: Build the `authorizeWithGithub` Mutation

Now that we have the code, we need to pass that back to GitHub to obtain a token and the user's information. First, we'll add the AuthPayload type. This will return the token and all user details. This is the type that will be returned from the authorizeWithGithub mutation. Let's add both to the schema:

type AuthPayload {
  githubToken: String!
  user: User!
}

type Mutation {
  ...
  authorizeWithGithub(code: String!): AuthPayload!
}

The AuthPayload type is used only as a response to authorization mutations. It contains the user who was authorized by the mutation along with a token that they can use to identify themselves during future requests.

Before we program the authorizeWithGithub resolver, we'll need to build two functions to handle GitHub API requests: one to ask for the token and then other to ask for the account info. requestGithubToken will ask for the token:

const requestGithubToken = credentials =>
  fetch("https://github.com/login/oauth/access_token", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Accept: "application/json"
    },
    body: JSON.stringify(credentials)
  })
    .then(res => res.json())
    .catch(error => {
      throw new Error(JSON.stringify(error));
    });

The requestGithubToken function returns a fetch promise. The credentials are sent to a GitHub API URL in the body of a POST request. The credentials consist of the client_id, client_secret, and code. Once completed, the GitHub response is then parsed as JSON. We can now use this function to request a GitHub access token with credentials.

Once we have a GitHub token, we will need to access information from the current user's account. Specifically, we'll want their GitHub login, name, and profile picture. To obtain this information, we will need to send another request to the GitHub API along with the access token that we obtained from the previous request.

const requestGithubUserAccount = token =>
  fetch(`https://api.github.com/user?access_token=${token}`).then(
    res => res.json
  );

This function also returns a fetch promise. On this GitHub API route, we can access information about the current user so long as we have an access token.

Now let's combine both of these requests into a single asynchronous function that we can use to authorize and return a user from GitHub, requestGithubUser:

const requestGithubUser = async credentials => {
  const { access_token } = await requestGithubToken(credentials);
  const githubUser = await requestGithubUserAccount(access_token);
  return { ...githubUser, access_token };
};

Using async/await here makes it easier to handle multiple asynchronous requests. First, we request the access token and wait for the response. Then, using the access_token, we request the GitHub user account info and wait for a response. Once we have the data, we'll put it all together in a single object.

We have the user details. Now we need to store this somewhere. In a production app, this would be stored in the database and added to our GraphQL server's context so that all of the resolvers would have access to that data. Think of context as being like a store where you can put data, authentication details, or anything else a resolver function needs to know about. In this case, we're going to keep this brief, and add everything to a variable called currentUser that we'll create at the top of this file.

let currentUser;

Then we can overwrite that with the user details in the authorizeWithGithub function.

We've created the helper functions that will support the functionality of the resolver. Now, let's actually write the resolver to obtain a token and a user account from GitHub:

async authorizeWithGithub(parent, { code }) {
  // 1. Obtain data from GitHub
    let githubUser = await requestGithubUser({
      client_id: <YOUR_CLIENT_ID_HERE>,
      client_secret: <YOUR_CLIENT_SECRET_HERE>,
      code
    })
  // 2. Package the results in a single object, write the value to currentUser global variable
    currentUser = {
      name: githubUser.name,
      githubLogin: githubUser.login,
      githubToken: githubUser.access_token,
      avatar: githubUser.avatar_url
    }
  // 3. Return user data and their token
    return { user: currentUser, token: access_token }
  }

Resolvers can be asynchronous. We can wait for a network response before returning the result of an operation to a client. The authorizeWithGithub resolver is asynchronous because we have to wait for two responses from GitHub before we'll have the data that we need to return.

It's time to test this authorization process, and to test, you need a code. To obtain the code, you'll need to run the githubLoginUrl query.

Paste the url into the location bar of a new browser window. You will be directed to GitHub where you will agree to authorize this app. When you authorize the app, GitHub will redirect you back to http://localhost:3000 with a code:

http://locahost:3000?code=XYZ

Here, the code is XYZ. Copy the code from the browser URL and send it to the authorizeWithGithub mutation:

mutation {
  authorizeWithGithub(code: "XYZ") {
    token
    user {
      githubLogin
      name
      avatar
    }
  }
}

This mutation will authorize the current user and return a token along with information about that user. Save the token. We'll need to send it in the header with future requests.

Note: When you see the error "Bad Credentials", it means that the client id, client secret, or code that was sent to the GitHub API is incorrect. Check the client id and client secret, but often it's the code that causes this error. GitHub codes are only good for a limited time period, and they can only be used once. If there is a bug in the resolver after the credentials were requested, the code used in the request will no longer be valid. Typically, you can resolve this error by requesting another code from GitHub.

Authenticating Users

In order to identify yourself in future requests, you will need to send your token with every request in the Authorization header. That token will be used to identify the user by looking up their database record.

GraphQL Playground has a location where you can add headers to each request. In the bottom corner, there is a tab right next to "Query Variables" called "HTTP Headers". You can add HTTP Headers to your request using this tab. Just send the headers as JSON:

{
  "Authorization": "Bearer <YOUR_TOKEN>"
}

Replace <YOUR_TOKEN> with the token that was returned from the authorizeWithGithub mutation. Now you are sending the key to your identification with each GraphQL request.

Step 3: Create a `me` Query

To bring this auth process full circle, we need to create one more query. Consider a user interface for any app where you have to log in. Once you provide valid credentials, there's typically a new element on the screen to reflect that logged in state. In other words, if I log in to Twitter, I will see my face in the upper right hand corner. Let's create a query that will return the currently logged in user's details.

First, we will need to modify our typeDefs:

type Query {
  me: User
  ...
}

The me query returns a nullable user. It will be null if a current authorized user is not found. Let's add the resolver for the me query:

const resolvers = {
  Query: {
    me: () => currentUser,
    ...
  }
}

We've already done the heavy lifting of looking up the user based on their token. At this point, you'll simply return the currentUser object. Again, this will be null if there is not a user.

If the correct token has been added to the HTTP Authorization header, you can send a request to obtain details about yourself using the me query:

query currentUser {
  me {
    githubLogin
    name
    avatar
  }
}

When you run this query, you will be identified. A good test is to try to run this query without the authorization header or with an incorrect token. Given a wrong token or missing header, you'll see that the me query is null.

There is no "one true way" to handle user authentication and authorization with GraphQL, but using a social OAuth solution like GitHub can be a quick way to get started. The process of passing tokens might differ slightly for Facebook, Google, or Auth0, but the main ideas will be consistent. We can use mutations to authenticate and authorize users and then with the data saved about a valid user, we can write queries for that user data.

In the next part of this series, we will look at how to set up authorization with GraphQL clients, specifically Apollo Client.