Building with GraphQL

In order to create and maintain any kind of system you need to be able to perform operations on your data. GraphQL solves some very specific problems to do with how you perform CRUD operations. However it is pretty important to understand some of the limitations with restful routing before graphQL makes any sense at all. 

At its best, rest provides a clear architectural style for Client server interations, and you can read more about that here.

RESTFUL ISSUES

Suppose you want to make a POST, PUT, GET or DELETE request to a standard blog application such as POST /<blog_name> or UPDATE /<blog_name>/:id it’s simple and almost English. 

Then extend the example to start with a user such as POST /<username>/:id/<blog_name>/ and we want to make the application posts start from a user and then post a new blog article.

The issue becomes that in order to do what you need to in practice, you need to put more and more information together which means one of two strategies. You either break restful conventions by making endpoints such as /user/23/friends_with_companies_and_positions/ which is not good because you’ve squished too much information together or a lot of endpoints which is painful to maintain.

In summary restful routing with highly relational data can become overwhelming. It also causes endless engineering discussions about the api strategy.

GRAPHQL

GraphQL is rather based on a graph in which you traverse the graph to collect the necessary information in response to a request. For example you might start with a user, expand that to users, then collect all companies associated with users. 

It’s important to remember that GraphQL is just one small component part of an app. When traffic hits the app many things happen, and one of the things is a check to see if this is a graphql call, and if so then it will be forwarded onto GraphQL where it can make GraphQL type interactions.

SCHEMA

when using graphQL you must have a schema which informs GraphQL about your data’s structure and relationships. This is named schema.graphql and it looks something like this.

type Book { title: String author: Author } 
type Author { name: String books: [Book] }

Using a schema to full effect you should design it around the operations of your clients. There are basically just 3 types of query that they can use

• Query – for retrieving data
• Mutation – for modifying data
• Subscription – for receiving notifications about data

As an application grows so does the schema, and making sure those changes dont break current implementations is the real art of using GraphQL.

Fragments

A GraphQL fragment is a reusable piece of a GraphQL query that allows you to define a set of fields that you want to retrieve from a GraphQL server. Fragments help you avoid redundancy in your queries and make your code more organized and maintainable. They are an essential part of GraphQL’s query composition and reuse capabilities.

Here’s an example of how you might use a GraphQL fragment:

# Define a fragment to retrieve basic user information
fragment UserInfo on User {
  id
  username
  email
}

# Use the UserInfo fragment in a query
query {
  currentUser {
    ...UserInfo
  }
}

# Use the same UserInfo fragment in another query
query {
  getUser(id: 123) {
    ...UserInfo
  }
}

In this example, the `UserInfo` fragment is defined with common fields for a user. It is then included in both queries (`currentUser` and `getUser`) to retrieve the same set of user information without duplicating the field selection.

And finally here is the practical application of a GraphQL query to a geospatial app I’m working on.

Thanks for reading,

Lucas