Accept RESTful API requests with your GraphQL/Express Server
The MONARQ library is a lightweight middleware package that allows GraphQL servers to accept RESTful API requests
The overlooked problem with making the jump to GraphQL
Not everybody can easily hop on the GraphQL train. Since the early 2000s, REST-style architecture has been the way applications were built to make API requests. Despite the advent of GraphQL and its rapid adoption, two decades worth of code is not instantly compatible with GraphQL. While you may have made the transition to GraphQL, many of your clients, both internal and external, may not have. Yet they still need to interact with your application and access data. Clients may not have the resources to transition to GraphQL, or fear migrating their codebase would cause a litany of breaking changes. These obstacles should not stop you from providing API access to all of your clients.
How MONARQ solves that
MONARQ is a service on top of GraphQL that allows data consumers to avoid the paradigm shift and corresponding learning curve. Our npm package allows you to specify the REST endpoints that you would like to expose and adds a simple Express Router to parse those requests into GraphQL queries, which can be handled by your existing backend architecture. Once MONARQ is implemented, your clients will be able to send standard REST API requests to the designated endpoints that you have exposed and your application will handle them with ease. With some simple user inputs into two functions, you now have a new Express Router instance that will be populated with predefined paths that will interpret which GraphQL query should be executed.
This allows the backend developers to integrate the result into the server, without the need to alter your workflow. We work with your code, not the other way around.
You had me at GraphQL, now let’s get started
The first step is to decide on the endpoints and actions that you want to expose through your new RESTful gateway. To do this, you’ll create a Manifest Object. The Manifest Object is the legend that lays out all supported REST endpoints, their corresponding HTTP methods, and their corresponding GraphQL operations. This requires that you already have a functioning GraphQL schema, but if you don’t, just make sure to set that up before moving on.
You’ll have to follow a specific blueprint for structuring the object, but it’s incredibly simple. As shown in the example below, the Manifest Object is a nested object with a series of keys that describe the available REST endpoints. Check out our GitHub for full details.
Lines 3–7 add support for GET requests sent to the path of /book/:id (where the user specifies the id of the book). You decide which GraphQL operation should be executed when this request is made. In this case, the ‘getBook’ query.
The client will send the request as a standard REST request. MONARQ will catch it, then parse it into a GraphQL query corresponding to the ‘getBook’ query type. The router will then pass it along to your server to respond to the query, just as it would for a GraphQL request. The response is unadulterated so it maintains the structure that your server already has in place.
The Manifest Object can be created manually in your directory. Or…
Create your Manifest Object with ease
We get it, all your coworkers write the ugliest mess of code a mother couldn’t love. Like you don’t, your code is totally amazing, it’s beyond scale. Basically a binary moby dick. But just in case you wanted your “co-workers” lives to be a little easier. We created a prototyping Manifest Builder app on our site, now all the pain of formatting and having precision syntax is gone.
One less bug for the books, the future is pretty cool.
Bringing it All Together
Once you’ve built your Manifest Object, all it takes is a few lines of code to finish implementing MONARQ. You’ll invoke two functions and define one within your main server file.
There are two core functions that make the magic happen. The first one, queryMap, maps the operations that you’ve included in your Manifest Object to GraphQL query strings. These query strings will be used once the request has been converted from REST to GraphQL. MONARQ generates the fully expanded version of the query for any operations mapped to a REST endpoint.
The second one, routerCreation, generates an Express Router, which contains route handlers for each REST endpoint. When a request is received, the route handlers will invoke a GraphQL query execution for the corresponding query generated by queryMap.
One of the required arguments for routerCreation is an execute function. This is the function that you’ll define, and should be whatever method your server is currently using to execute GraphQL queries, wrapped in an executeFn function in order to standardize inputs. This gives you the flexibility to use whatever method you prefer for executing GraphQL queries. In the example below, the native graphql method from GraphQL.js is used.
Once the router is created, implement it into your Express server with a route handler for all incoming REST requests. Do this by choosing a top-level path for all REST endpoints, for example ‘/api’.
With that, your application is ready to accept both REST and GraphQL requests!
Complete the metamorphosis!
MONARQ is just getting started! Send us your comments, questions, suggestions, constructive feedback (this isn’t reddit), and thoughts of any other fun features you’d love to see implemented. We love building cool stuff for you :)
Happy Querying!
Email us! monarq.team@gmail.com
Meet the MONARQ team
Peter Baniuszewicz | LinkedIn| Github
Tyler Kneidl | LinkedIn| Github
Helen Regula | LinkedIn| Github
MONARQ is a beta product developed under OSLabs
