{"id":20826,"date":"2018-02-09T12:15:08","date_gmt":"2018-02-09T10:15:08","guid":{"rendered":"https:\/\/www.webcodegeeks.com\/?p=20826"},"modified":"2018-02-09T10:22:20","modified_gmt":"2018-02-09T08:22:20","slug":"graphql-api-gateway-microservices","status":"publish","type":"post","link":"https:\/\/www.webcodegeeks.com\/web-development\/graphql-api-gateway-microservices\/","title":{"rendered":"GraphQL as an API Gateway to Microservices"},"content":{"rendered":"

GraphQL<\/a> was released to the public back in 2015, and like an animal raised in captivity, its first steps out in the wild were timid and went largely unnoticed. By now, however, it has garnered some major buzz, and with good reason: it solves some of the trickiest problems that are inherent in standard REST API architecture.<\/p>\n

Specifically, GraphQL allows you to evolve your API naturally without versioning, it provides workable documentation, it avoids the problems of over- and under-fetching, and it offers a convenient way to aggregate data from multiple sources with a single request. You can start to appreciate its power and flexibility once you get past its unconventional approach and its deceptive \u201clooks-like-JSON\u201d syntax (this coming from the same people who brought us React and its \u201clooks-like-HTML\u201d syntax).<\/p>\n

How can GraphQL be leveraged in an API gateway? It seems like it might be a perfect solution for interacting with multiple microservices, each dedicated to a single resource type. Well, the good news is that you can<\/em> use GraphQL in your API Gateway, and it can live alongside standard REST routes. So in some cases, you can have your cake and eat it too.<\/p>\n

GraphQL in a Nutshell<\/h2>\n

Before we get into the gateway code, let\u2019s review the landscape of GraphQL a bit. Unlike REST applications, GraphQL implementations rely on a single endpoint. All GraphQL requests post data (always<\/em> post, never get) to that one endpoint with the query that describes which resources and fields are being requested.<\/p>\n

GraphQL distinguishes between read operations as \u201cqueries\u201d and write operations as \u201cmutations.\u201d To support queries, your GraphQL implementation will define a root query object that enumerates all the resource types available for querying (along with their fields and data types). You can think of this as something like a database schema that defines tables and columns.<\/p>\n

To support mutations, your GraphQL implementation will define a root mutation object that enumerates all the available mutations and their properties. The mutations can be thought of as actions, eg<\/em>, createUser<\/code> or updateOrder<\/code>. Even within a single language or framework, there is no standard structure for where these GraphQL components should exist, but these critical elements must exist somewhere in any GraphQL implementation.<\/p>\n

Using Both GraphQL and REST Endpoints<\/h2>\n

Just because our API gateway has a GraphQL endpoint defined doesn\u2019t mean we can\u2019t have other endpoints too! It is entirely possible to define traditional REST routes in the same application.<\/p>\n

Since we want to avoid duplicating code in the gateway, especially the code that makes requests out to the microservices, we have to choose which of our methodologies will be in charge. We could either dissect a GraphQL query and translate it into its corresponding REST requests, or we could translate a REST request into its GraphQL equivalent.<\/p>\n

It turns out that the latter is simpler, so that\u2019s the trick we are proposing: translate requests made to REST routes into GraphQL. No code that interacts with the microservices needs to be duplicated because the REST routes simply act as a translation layer for GraphQL.<\/p>\n

In Code<\/h2>\n

Now that we have described our plan of attack, let\u2019s look at some code! The repository<\/a> that demonstrates these examples is available on Github<\/a><\/p>\n

This is a Node.js application using the popular Express<\/a> framework. You should be able to clone and install the application following the instructions in the README.<\/p>\n

Running yarn run start<\/code> from the command line should fire up the application and start listening on port 4000. Point your browser to http:\/\/localhost:4000\/graphql<\/code> to have a look at the GraphQL endpoint. The righthand side will show you any registered resource types and their fields, so right away you can see how GraphQL offers some workable documentation.<\/p>\n

We can run an example query to look up a single user by their ID:<\/p>\n

{\r\n  users(_id: 3){\r\n    name\r\n  }\r\n}\r\n```\r\n\r\nThe result should be:\r\n```\r\n{\r\n  \"data\": {\r\n    \"users\": [\r\n      {\r\n        \"name\": \"Tammy\"\r\n      }\r\n    ]\r\n  }\r\n}<\/pre>\n
The code that handles this is inside src\/users.js<\/code>, and it revolves around the GraphQLObjectType<\/code> object. That\u2019s what gives the response its structure and provides workable documentation.<\/p>\n
REST Equivalent<\/h2>\n
Next, let\u2019s look at how we might support a REST endpoint that fetches this same data. A conventional route to look up a single user record would follow the pattern of \/users\/:userId<\/code>. Take a look inside the index.js<\/code> and see how it registered the route:<\/p>\n
const users = require('.\/src\/rest\/user');\r\n\/\/ ... \r\napp.use('\/users', users);<\/pre>\n
That\u2019s pretty standard Express routing stuff. Let\u2019s take a look at the src\/rest\/user.js<\/code> file to see how it converts the request into GraphQL.<\/p>\n
const app = require('express');\r\nconst router = app.Router();\r\nimport rootSchema from '..\/app';\r\n\r\nimport {graphql} from 'graphql'\r\n\r\nconst query = (q, vars) => {\r\n    return graphql(rootSchema, q, null, null, vars)\r\n}\r\n\r\n\/\/ Transform response to JSON API format \r\n\/\/ (if desired)\r\nconst transform = (result) => {\r\n    const user = result.data.users[0];\r\n\r\n    return {\r\n        data: {\r\n            type: 'user',\r\n            id: user._id,\r\n            attributes: {\r\n                name: user.name\r\n            }\r\n        }\r\n    }\r\n}\r\n\r\n\r\n\/\/ REST request to get a user\r\nrouter.get('\/:userId', (req, res) => {\r\n    \/\/ Convert the request into a GraphQL query string\r\n    query(\"query{users(_id:\" + req.params.userId + \"){_id, name}}\")\r\n        .then(result => {\r\n            const transformed = transform(result)\r\n            res.send(transformed)\r\n        })\r\n        .catch(err => {\r\n            res.sendStatus(500)\r\n        })\r\n})\r\n\r\nmodule.exports = router;<\/pre>\n
This is really where the magic happens. The registered callback for the route assembles the query string and passes it to GraphQL:<\/p>\n
query(\"query{users(_id:\" + req.params.userId + \"){_id, name}}\")<\/pre>\n
The query string maps out a query object in that \u201cJSON-like\u201d syntax \u2014 yes, it seems redundant, but there is a root query node there that wraps the part of the query that we used on the interactive GraphQL page.<\/p>\n
This approach may remind you of the old days before ORMs where you had to assemble query strings by hand. It may be more appropriate to filter the request parameter before putting it into a query string, but since it gets interpreted by GraphQL, it\u2019s probably safe \u2014 GraphQL will simply choke if the string is not valid.<\/p>\n
Included in this output is a transformer function that alters the default GraphQL response into JSON API<\/a> format, but that may or may not be something you wish to keep.<\/p>\n
You should be able to see this REST endpoint in action by requesting URLs like http:\/\/localhost:4000\/users\/2<\/a> and getting responses like:<\/p>\n
{\r\n    \"data\": {\r\n        \"type\": \"user\",\r\n        \"id\": \"2\",\r\n        \"attributes\": {\r\n            \"name\": \"Jo\u00e3o\"\r\n        }\r\n    }\r\n}<\/pre>\n
Requesting a Microservice<\/h2>\n
A more complex example involves actually hitting a microservice with a web request. This has been done by requesting an inspirational quote of the day from http:\/\/quotes.rest\/qod.json?category=inspire<\/a>.<\/p>\n
In order to add GraphQL support for this data, we need to do three things:<\/p>\n
    \n
  1. Modify the root query object in src\/app.js<\/code>.<\/li>\n
  2. Define the Quote resource type in src\/quote.js<\/code>.<\/li>\n
  3. Define a service that will fetch the quote data from a remote API in src\/services\/quote.js<\/code>.<\/li>\n<\/ol>\n
    Modify the root query<\/h3>\n
    First we need to add the resource type to the GraphQL root query object inside src\/app.js<\/code>:<\/p>\n
    \/\/ src\/app.js\r\nimport {\r\n    GraphQLObjectType,\r\n    GraphQLSchema,\r\n} from 'graphql\/type';\r\n\r\nimport userQuery from '.\/users';\r\nimport agendaQuery from '.\/agenda-interface';\r\nimport quoteQuery from '.\/quote';\r\n\r\nconst query = new GraphQLObjectType({\r\n    name: 'RootQueryType',\r\n    fields: {\r\n        users: userQuery,\r\n        agenda: agendaQuery,\r\n        quote: quoteQuery\r\n    },\r\n});\r\n\r\nexport default new GraphQLSchema({\r\n    query,\r\n});<\/pre>\n
    Define the query type<\/h3>\n
    The quote query object is defined in src\/quote.js<\/code> \u2014 this is almost exactly the same structure as the one used for the user query, but it references a service class whose job it will be to interact with the remote microservice.<\/p>\n
    \/\/ src\/quote.js\r\nimport {\r\n    GraphQLObjectType,\r\n    GraphQLNonNull,\r\n    GraphQLString\r\n} from 'graphql\/type';\r\n\r\nimport { getQuote } from '.\/services\/quote'\r\n\r\nexport const QuoteType = new GraphQLObjectType({\r\n    name: 'Quote',\r\n    description: 'Quote of the day from API service',\r\n    fields: () => ({\r\n        id: {\r\n            type: GraphQLString,\r\n            description: 'Quote id',\r\n        },\r\n        quote: {\r\n            type: new GraphQLNonNull(GraphQLString),\r\n            description: 'The text of the quote',\r\n        },\r\n        author: {\r\n            type: GraphQLString,\r\n            description: 'The person to whom the quote is attributed',\r\n        },\r\n        date: {\r\n            type: GraphQLString,\r\n            description: 'Date in YYYY-MM-DD format',\r\n        }\r\n    })\r\n});\r\n\r\nexport default {\r\n    type: QuoteType,\r\n    resolve: getQuote\r\n}<\/pre>\n
    This all depends on the getQuote()<\/code> function, which we\u2019ll discuss next.<\/p>\n
    Define a service for retrieving remote data<\/h3>\n
    The getQuote()<\/code> function is defined inside src\/services\/quote.js<\/code>:<\/p>\n
    \/\/ src\/services\/quote.js\r\n\/**\r\n * This is where the app calls the microservice responsible for the \"Quote\" resource type.\r\n *\/\r\nimport fetch from 'universal-fetch'\r\n\r\nexport const\r\n    getQuote = () => {\r\n        const url = 'http:\/\/quotes.rest\/qod.json?category=inspire'\r\n        return fetch(url)\r\n            .then(response => {\r\n                return response.json()\r\n            })\r\n            .then(json => {\r\n                return transform(json)\r\n            })\r\n            .catch(err => {\r\n                console.trace(err)\r\n            })\r\n    }\r\n\r\n\/\/ Transform the raw microservice output into \r\n\/\/ fields\/types defined by the GraphQL type\r\nconst transform = (json) => {\r\n    const\r\n        { contents } = json,\r\n        { quotes } = contents,\r\n        quote = quotes[0]\r\n\r\n    return {\r\n        id: quote.id,\r\n        quote: quote.quote,\r\n        author: quote.author,\r\n        date: quote.date\r\n    }\r\n}<\/pre>\n
    The transform<\/code> method here converts whatever format is used by the microservice into the format defined by GraphQL for this resource type. If you need to add fields to your response, you\u2019ll have to add them to your QuoteType<\/code> object in src\/quote.js<\/code>.<\/p>\n
    Once these parts are complete, you should be able to make queries using GraphQL:<\/p>\n
    {\r\n  quote{\r\n    quote,\r\n    author\r\n  }\r\n}<\/pre>\n
    Add REST support<\/h3>\n
    As before, a route is registered inside the index.js<\/code> file:<\/p>\n
    const quotes = require('.\/src\/rest\/quote');\r\n\/\/ ...\r\napp.use('\/quote', quotes);<\/pre>\n
    The REST request acts as a translator to the GraphQL syntax.<\/p>\n
    \/\/ src\/rest\/quote.js\r\nconst app = require('express');\r\nconst router = app.Router();\r\nimport rootSchema from '..\/app';\r\nimport {graphql} from 'graphql'\r\n\r\nconst query = (q, vars) => {\r\n    return graphql(rootSchema, q, null, null, vars)\r\n}\r\n\r\n\/\/ Transform response to JSON API format \r\nconst transform = (result) => {\r\n    const quote = result.data.quote;\r\n\r\n    return {\r\n        data: {\r\n            type: 'quote',\r\n            id: quote.id,\r\n            attributes: {\r\n                quote: quote.quote,\r\n                author: quote.author,\r\n                date: quote.date\r\n            }\r\n        }\r\n    }\r\n}\r\n\r\n\/\/ REST request to get a quote\r\nrouter.get('\/', (req, res) => {\r\n    \/\/ Convert the request into a GraphQL query string\r\n    query(\"query{quote{id, quote, author, date}}\")\r\n        .then(result => {\r\n            const transformed = transform(result)\r\n            res.send(transformed)\r\n        })\r\n        .catch(err => {\r\n            res.sendStatus(500)\r\n        })\r\n})\r\n\r\nmodule.exports = router;<\/pre>\n
    When complete, the REST endpoint is available at http:\/\/localhost:4000\/quote<\/a>.<\/p>\n
    Note that the quote service has a limit of 10 requests per hour, so it the demonstration can only be used in moderation.<\/p><\/blockquote>\n
    Pros<\/h2>\n
    Now that you\u2019ve seen how you can have your API Gateway be both a GraphQL implementation and support standard REST routes, the benefits should be clear:<\/p>\n