FloodiQ.com Loves GraphQL
When you are on a website, what you see on your browser is usually known as the front end. For Flood iQ, this includes the search bar, flood maps, and flood details. What you do not see is referred to as the backend. To illustrate this, imagine a car: although from the outside you can’t see the engine, you know it is an important component that helps the car run. You can think of the backend of Flood iQ as the engine that drives this tool.
The Flood iQ backend is written in JavaScript, specifically NodeJS. It runs a Koa HTTP server that hooks into a query language known as GraphQL. This query language is then hooked up to a non-relational database called MongoDB.
Why We Use GraphQL
GraphQL was first developed and used internally by Facebook. It allows us to make HTTP requests to a server using a query, and returns data that is specifically tied to that query.
Typically, without GraphQL, we would be using a model known as a RESTful service. With REST, you are given multiple endpoints and then query these endpoints based on the needs of your application. For example, for Flood iQ, let’s assume the following URL would return a Flood Risk Score for an address:
GET /flood-data/<address>/risk-scoreGreat! But now consider that we also need the address to show a bar graph for each of the following: property flooding, neighborhood flooding, sea level rise and water depth. If we built a proper RESTful service that abstracts data within our application, we would have to make five HTTP requests in order to return this data for an address:
GET /flood-data/<address>/property
GET /flood-data/<address>/neighborhood
GET /flood-data/<address>/sea-level-rise
GET /flood-data/<address>/water-depthWe could theoretically aggregate this into one URL and control it with URL parameters:
GET /flood-data/<address>/?filters=property|neighborhood|sea-level-rise|water-depthBut building Flood iQ’s backend that way would make it difficult to scale and manage in the long run. This is where the fundamentals of GraphQL kick in.
GraphQL gives us one endpoint that allows us to move fast and build our Flood iQ application at scale. Using GraphQL, we are able to define a data schema based on our backend data models, so that instead of making five requests we make only one, with a specific query pertaining to the application’s view:
GET /Query PropertyQuery($address: String!) {
floodData(address: $address) {
riskScore
property
neighborhood
seaLevelRise
waterDepth
}
This significantly simplifies the request, but GraphQL allows for even more versatility. The example above runs a query for an address requesting a risk score, property and neighborhood flood data, and sea level rise and water depth data. In our current Flood iQ application user flow, when a user requests information about an address, they are first given a risk score. This means the only data point we need initially is riskScore. The other fields should not populate until the user requests more flood details.
To solve for this, we can fragment our larger query:
GET /Query PropertyQuery($address: String!) {
floodData(address: $address) {
riskScore
...MoreMapDetailsFragment
}
}
This allows us to feed only the required information to our application’s view at that point, and cache the fragment for use at a later time. Then, since we’ve already made our query request, we do not have to make an additional HTTP request to gather more data.
The front end of Flood iQ was built using ReactJS and Relay. Thanks to these amazing open-source technologies, we can declare our view layer (components) directly with a GraphQL query, and colocate our queries with these views using Relay. This allows Flood iQ to make smart decisions about making network requests, ultimately speeding up our application for our users!
