How to Build a GraphQL Data Layer for REST Microservices

GraphQL is a great technology for microservices because you can use it as a data layer for these microservices. One use case is to combine the data from all these services into a single, unified API. But building this data layer can be very time-consuming since you need to connect the microservices into one schema. In this post, you'll learn step-by-step how to build a data layer for microservices with GraphQL in a declarative way. : The complete source code for this post can be found . TL;DR here Why use GraphQL for Microservices? Whenever you have a microservices architecture, you often don’t want to expose this architecture to the (front-end) clients that consume it. But you use a data layer (or gateway) that serves as the entry point to your microservices. . This way you don’t give any critical information about your microservice orchestration away, which makes it less prone to hackers By having one single entry to your microservices, you reduce the number of requests from your clients to these services. Calls to-- for example-- your authentication service to verify a token before every request, don’t have to be repeated from the client. Also, the data layer saves you (and others consuming your APIs) time documenting and specifying all the APIs from the microservices. The microservices that are consumed through this data layer don’t necessarily have to use GraphQL themselves. By using a tool called StepZen, you can create a data layer for REST microservices, without having to write any code. Instead, you can connect the microservices using GraphQL SDL (Schema Design Language) only. For every microservice, a GraphQL schema must be created, which can then be combined together into one GraphQL schema with StepZen. Let’s see how this would work. Building a Data Layer Using GraphQL Now you’ve learned why a data layer is helpful for your microservices, it’s time to learn how you can build such a data layer. There are many ways to create a data layer by creating a custom GraphQL server, but this is very time-consuming and error-prone. Luckily, the tool StepZen makes it easier to create a GraphQL data layer (or server) by writing GraphQL SDL only. By using this declarative approach you don’t only save time writing code, but it also means you don’t have to handle the deployment of the data layer yourself. StepZen deploys the data layer for you automatically on every save. Let’s create the data layer, based on three (mocked) REST microservices that you can find in . this Github repository Setting up the Project The README of the project has all the information on running the mock REST microservices, by using or . npm yarn First, you need to clone the repository to your local machine and install the JavaScript dependencies. After which you can run either or . npm start yarn start The REST microservices can then be found on ports to , but also through an HTTPS tunnel. StepZen needs your microservices to be available though HTTPS, and therefore I use the tool . You don’t have to install this tool separately, as it was already installed from the projects’ dependencies. localhost 3001 3003 Localtunnel After starting the project, something like this will be logged to your terminal: Posts service is running on https://lorem-mouse-38.loca.lt Users service is running on https://smart-robin-23.loca.lt Auth service is running on https://mouse-trap-12.loca.lt What is logged to terminal are the hostnames for the HTTPS tunnels to the mocked REST microservices. The Posts service in example can be visited in the browser at , but also via the HTTPS tunnel at . http://localhost:3003/api/posts https://lorem-mouse-38.loca.lt/api/posts You need to add these hostnames to the file for every service, so StepZen can use them to create the data layer: config.yaml ## config.yaml configurationset: - configuration: name: auth_service client_id: test client_secret: test123 hostname: 'mouse-trap-12.loca.lt' - configuration: name: posts_service hostname: 'lorem-mouse-38.loca.lt' - configuration: name: users_service hostname: 'smart-robin-23.loca.lt' We continue by create a GraphQL schema for the services that are now connected through the HTTPS tunnel. Creating Schemas for Microservices First, we’ll create a GraphQL schema for the authentication service. This service is available on the endpoint , and the hostname that was generated by Localtunnel - which is different every time you start the microservices. From this endpoint you can create an authorization token using OAuth. /api/token The OAuth flow for client credentials is applied, which lets you create a token by calling . The authentication service will return a Bearer token if the values for and are correct. The GraphQL schema to reflect the authentication service can be found in : https://$hostname/api/token?grant_type=client_credentials&client_id=$client_id&client_secret=$client_secret $client_id $client_secret services/auth/index.graphql ## /services/auth/index.graphql type Auth { id: Int! access_token: String! } type Query { token: Auth @rest( endpoint: "https://$hostname/api/token?grant_type=client_credentials&client_id=$client_id&client_secret=$client_secret" configuration: "auth_service" ) } The query called is using the custom directive , which can be used to define a REST data source that will be called by StepZen. From the file , the values for and will be retrieved. token @rest config.yaml $client_id $client_secret This query from the authentication service is how the other microservices can get the authorization token needed in the OAuth flow. For the microservice that gets posts, it means it should have the token before it’s able to retrieve the posts. The schema for the posts service is in : services/posts/index.graphql ## /services/posts/index.graphql type Post { id: Int! title: String! imageUrl: String! author: Int } type Query { posts(access_token: String!): [Post] @rest( endpoint: "https://$hostname/api/posts" headers: [{ name: "Authorization", value: "Bearer $access_token" }] configuration: "posts_service" ) getPosts: [Post] @sequence(steps: [{ query: "token" }, { query: "posts" }]) } The schema for the posts service has two queries: one to retrieve the posts, and one to retrieve the token and then get the posts. A custom directive called is used to combine the query from this GraphQL schema with the query from the authentication service. @sequence posts token The response of the query is used as input for the query, which allows you to return the posts when the token can be retrieved. token posts You can reuse this setup for the users service, that also has a query to get the users with the token. The schema for this REST microservice can be found in : /services/users/index.graphql ## /services/users/index.graphql type User { id: Int! name: String! } type Query { user(id: Int!, access_token: String!): User @rest( endpoint: "https://$hostname/api/users/$id/" headers: [{ name: "Authorization", value: "Bearer $access_token" }] configuration: "users_service" ) getUser(id: Int!): User @sequence(steps: [{ query: "token" }, { query: "user" }]) } The GraphQL schemas for the three REST microservices in this project need be combined into one GraphQL schema. This happens in : index.graphql ## index.graphql schema @sdl(files: ["services/auth/index.graphql", "services/posts/index.graphql", "services/users/index.graphql"]) { query: Query } Finally, in the file the endpoint to which the GraphQL data layer will be deployed is defined. In this project it’s set to , meaning when you run the command to start (and deploy) the GraphQL server the GraphiQL playground becomes locally available at . stepzen.config.json /api/datalayer http://localhost:5000/api/datalayer You can run to combine the GraphQL schemas from all the REST microservices, which will then be deployed to StepZen: stepzen start After running this command you can start developing applications that consume this GraphQL data layer instead of the microservices directly. Summary Great work! You’ve learned how to create a GraphQL data layer for REST microservices, using GraphQL SDL only. This is done with the tool StepZen, which has a generous free tier. With StepZen you cannot only create a data layer for REST microservices, but you can also create individual GraphQL APIs. You can learn more about this by looking through StepZen documentation. Previously published here.