Create a Book Rating System With the Goodreads API and Slash GraphQL

GraphQL is a relatively new way to build user interfaces and APIs for consumers. It's essentially a querying language backed by a strongly typed schema, making it easy to write human-readable requests to get exactly the data you need. Compared to REST, whose responses are dictated by the server, GraphQL queries place the power squarely in the client's hands.

However, GraphQL is really just a spec that describes an API. Many features one might expect from an API, like authorization/authentication logic, bi-directional communication, or rate-limiting, still need to be implemented. Recently launched, Slash GraphQL is a fully managed GraphQL backend that takes care of all the hard work of setting up a GraphQL API, letting you concentrate on building your app.

In this article, we'll be building an e-commerce bookstore that relies on Slash GraphQL. To demonstrate the service's flexibility, we'll also be fetching data from another source — the Goodreads API — and integrate it into our responses.

We'll be building our app using Node.js, so you should have at least version 12 installed on your machine. Create a directory called slashql_bookstore and navigate into it from the command line.

Creating the GraphQL Backend

Setting Up Slash GraphQL

Setting up an account on Slash GraphQL is easy — you can instantly sign-in with your GitHub account. The platform has a free trial you can use for this walkthrough. 

After you've created an account, you'll need to create a new backend:

1. Click on "Launch a New Backend."

2. Name the backend "Bookstore."

3. Click "Launch."

That's it! You now have a server spun up for you in an AWS region.

Defining the GraphQL Schema

Every GraphQL server has a strongly typed schema, which defines the objects and fields available to consumers.

Click on "Schema" and paste the following lines:

xxxxxxxxxx

type Book {

  id: Int!

  isbn: Int!

  title: String! @search(by: [fulltext])

  author: Author!

}

type Author {

  id: Int!

  firstname: String!

  lastname: String!

}

Here we've defined two types — 'Book' and 'Author' — representing the data in our API. Slash GraphQL provides support for custom directives is one of the most convenient of its many niceties. Here, for example, by annotating the 'title' field with @search, we can provide a fuzzy text with no additional work.

Click "Deploy" to send this schema to production.

Setting Up the Data

Let's move on to inserting data. We can use the API Explorer not only to add data but query it, too. To populate our GraphQL backend, we'll define a list of books and their authors through a mutation that Slash GraphQL conveniently provides for us, based on our schema:

xxxxxxxxxx

mutation AddData {

  addBook(input: [

    {id: 1, title: "The Sound and The Fury", isbn: 9780394747743, author: {id:1, firstname: "William", lastname: "Faulkner"}},

    {id: 2, title: "Light in August", isbn: 9780394711898, author: {id:1, firstname: "William", lastname: "Faulkner"}},

    {id: 3, title: "Giovanni's Room", isbn: 9780141032948, author: {id:2, firstname: "James", lastname: "Baldwin"}},

    {id: 4, title: "The Fire Next Time", isbn: 9780140182750, author: {id:2, firstname: "James", lastname: "Baldwin"}},

    {id: 5, title: "To The Lighthouse", isbn: 9780140274165, author: {id:3, firstname: "Virginia", lastname: "Woolf"}},

    {id: 6, title: "Orlando", isbn: 9780241284643, author: {id:3, firstname: "Virginia", lastname: "Woolf"}}

    ]) {

  numUids

  }

}

Click the giant Play button to have this data added to the backend. 

Now, let's run a query to verify that this data is present:

xxxxxxxxxx

query GetBooks {

  queryBook {

    title

    isbn

    author {

      firstname

      lastname

    }

  }

}

You should see a response back that shows all of the data you previously inserted. 

Building the Server

We'll now use Express to set up a basic API server to provide users access to this Slash GraphQL source. Our Express server acts as little more than an interface to hand requests off to Slash GraphQL. Its most important lines are these:

const BACKEND_URL = "https://rampant-arm.us-west-2.aws.cloud.dgraph.io/graphql"

async function fetchGraphQL(operationsDoc, variables) {

  const result = await axios({

    method: 'POST',

    url: BACKEND_URL,

    headers: {

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

    },

    data: JSON.stringify({

      query: operationsDoc,

      variables,

    }),

  })

  return result.data

}

const query = `

query {

  queryBook {

    title

    isbn

    author {

      firstname

      lastname

    }

  }

}

`

app.get('/', jsonParser, async (req, res) => {

  let gqlResponseData = await fetchGraphQL(query,  {})

  res.render('index', { books: gqlResponseData.data.queryBook })

})

Here, we've defined a helper function, fetchGraphQL, which sets up the necessary headers and data to send over to Slash GraphQL. Keep in mind that you'll need to change BACKEND_URL to match the URL that Slash GraphQL gives you. Then, we write a GraphQL query that defines the data that we want. Finally, we set up a route to fetch that data and then render it in our view:

xxxxxxxxxx

<div class="container">

  {{#each books}}

  <div class="row">

    <div class="col-md-4">

      <h2>{{title}}</h2>

      <h4>{{author.firstname}} {{author.lastname}}</h4>

      <p><strong>ISBN:</strong> {{isbn}}</p>

    </div>

  </div>

  <hr>

  {{/each}}

</div>

Our view is backed by Handlebars, which is a popular templating library. We can feed our JSON data into an HTML fragment and iterate over the keys and values, making it much easier to display the information. Here we're using an #each loop to go over every book returned by the GraphQL API and then plugging the data into HTML tags. You'll notice that we have placeholders that match the names of the JSON keys; these are replaced by the real data when the page is viewed.

After you npm install all the dependencies, run the server with node server.js. Then, head on over to localhost:3000 in your browser: 

You should get back the same response that Slash GraphQL's API Explorer gave.

Extend the Server

As a final step, we want to expose some reviewer data about these books. But we don't want to create dummy data here; instead, we'll use the Goodreads API. Make sure you set up an account there and get an API key before continuing.

One of the many things that Slash GraphQL excels at is stitching together disparate sources of data into one GraphQL interface. Perhaps you'll want to make calls to other API endpoints that are under your control. To support this, Slash GraphQL provides the @custom directive, which allows you to implement custom behavior for GraphQL fields and resolvers.

First, let's add our rating information to the existing schema:

xxxxxxxxxx

type Rating @remote {

  ratings_count: Int!

  average_rating: Float!

}

Our Rating type defines field names which we expect from the book.show_by_isbn API. We don't need to define every field that their REST API provides, only the ones we're interested in. Slash GraphQL will know how to transform that response into a GraphQL one.

On the field side of things, we'll need to specify the URL we want to call out to, along with the HTTP method:

xxxxxxxxxx

type Book {

  # ...

  rating: Rating @custom(http: {

  url: "https://goodreads-api-munger.glitch.me?isbn=$isbn",

  method: GET

  })

  # ...

}

You'll notice here that we're actually calling out to a Glitch project. The Goodreads API doesn't return JSON data in a nice, neat format. We'll call out to an intermediary server that will munge the data into a more legible format. This server's details aren't all that important (but you can check it out if you want to). It is important to note that this URL can stand in for anything, which can be super helpful if you're interacting with data that you own.

The other amazing thing is that Slash GraphQL will substitute data for you. See that part of the URL that says $isbn? Depending on the object returned by our query, Slash GraphQL will substitute in the real field value for that variable. This keeps your URL requests flexible and easy to manage.

That's all that we need to do to bring in some custom data. Our GraphQL query can now add this rating field to bring in that external data. Let's replace the query in our server.js with this one:

xxxxxxxxxx

const query = `

query {

  queryBook {

    title

    isbn

    rating {

      ratings_count

      average_rating

    }

    author {

      firstname

      lastname

    }

  }

}

`

    title

And, let's update the view to show this information:

xxxxxxxxxx

<div class="container">

  {{#each books}}

    <div class="row">

      <div class="col-md-4">

      <h2>{{title}}</h2>

      <h4>{{author.firstname}} {{author.lastname}}</h4>

      <p><strong>ISBN:</strong> {{isbn}}</p>

      <p>Rating: {{rating.average_rating}} (out of {{rating.ratings_count}} votes)</p>

    </div>

  </div>

  <hr>

  {{/each}}

</div>

If you restart the server and head back to localhost:3000, you should now see the ratings populated as well:

Conclusion

Slash GraphQL makes it incredibly easy to set up a production-grade GraphQL API, but we've only scratched the surface. In addition to combining disparate data locations, it also supports authorization, subscriptions, and even encryption.

You can grab the complete source code for this tutorial over at GitHub. If you haven’t already, be sure to sign up for Slash GraphQL — feel free to share your creations with the rest of the Dgraph community.