rest-wrapper

REST API Wrapper

Overview

This directory contains the service definition and file structure for a simple Graphcool service that wraps a REST API using resolver functions. Read the last section of this README to learn how the different components fit together.

The example is based on the free Dog API which allows to retrieve images of dogs that belong to certain breeds and subbreeds.

.
├── README.md
├── graphcool.yml
├── src
│   ├── allBreeds.graphql
│   ├── allBreeds.js
│   ├── allSubBreeds.graphql
│   ├── allSubBreeds.js
│   ├── breedImages.graphql
│   ├── breedImages.js
│   ├── randomBreedImage.graphql
│   ├── randomBreedImage.js
│   ├── randomDogImage.graphql
│   ├── randomDogImage.js
│   ├── randomSubBreedImage.graphql
│   ├── randomSubBreedImage.js
│   ├── subBreedImages.graphql
│   └── subBreedImages.js
└── types.graphql

Read more about service configuration in the docs.

Get started

1. Download the example

Clone the full framework repository and navigate to this directory or download only this example with the following command:

curl https://codeload.github.com/graphcool/framework/tar.gz/master | tar -xz --strip=2 framework-master/examples/rest-wrapper
cd rest-wrapper

Next, you need to create your GraphQL server using the Graphcool CLI.

2. Install the Graphcool CLI

If you haven't already, go ahead and install the CLI first:

npm install -g graphcool

3. Create the GraphQL server

The next step will be to deploy the Graphcool service that's defined in this directory.

To deploy the service and actually create your GraphQL server, invoke the following command:

graphcool deploy

When prompted which cluster you'd like to deploy, choose any of the Shared Clusters (shared-eu-west-1, shared-ap-northeast-1 or shared-us-west-2) rather than local.

Note: Whenever you make changes to files in this directory, you need to invoke graphcool deploy again to make sure your changes get applied to the "remote" service.

Testing the service

The easiest way to test the deployed service is by using a GraphQL Playground.

You can open a Playground with the following command:

graphcool playground

Inside the Playground, you can send queries for all the resolver functions that are defined inside graphcool.yml:

• allBreeds
• allSubBreeds
• randomDogImage
• randomBreedImage
• randomSubBreedImage
• breedImages
• subBreedImages

Here are are some sample queries you can send:

Get all breeds and their subbreeds

{
  allBreeds {
    name
    subBreeds
  }
}

Get all subbreeds of the hound breed

{
  allSubBreeds(breedName: "hound") {
    name
  }
}

Get a random dog image

{
  randomDogImage {
    url
  }
}

Get a list of of the afghan breed (subbreed of hound)

{
  subBreedImages(breedName: "hound", subBreedName: "afghan") {
    url
  }
}

What's in this example?

This example demonstrates how you can use Graphcool's resolver functions to wrap an existing REST API (a Dog API to retrieve images of certain breeds and their subbreeds).

Each resolver targets one dedicated endpoint from the API and effectively acts as a proxy to provide a GraphQL API for the existing REST endpoint.

For example, the allBreeds resolver provides the following API defined in allBreeds.graphql:

type AllBreedsPayload {
  name: String!
  subBreeds: [String!]!
}

extend type Query {
  allBreeds: [AllBreedsPayload!]!
}

It's implementation in allBreeds.js looks as follows:

require('isomorphic-fetch')

const url = 'https://dog.ceo/api/breeds/list/all'

module.exports = () => {
  return fetch(url)
    .then(response => response.json())
    .then(responseData => {
      const breedsListData = responseData.message
      const allBreeds = []
      Object.keys(breedsListData).map(breedName => {
        const breed = {
          name: breedName,
          subBreeds: breedsListData[breedName]
        }
        allBreeds.push(breed)
      })
      return { data: allBreeds }
    })
}

All that's happening in there is sending an HTTP request to the specified endpoint and convert the response into the format that's defined in the extension of the Query type above.