GraphQL, Not to be Forgotten

GraphQL has been around for over five years, and like a lot of technologies, it’s had its buzz worthy moments. Unfortunately, with the pace at which new technologies pop up, it’s easy for technologies to get pushed out of the conversation. GraphQL shouldn’t be one of these forgotten technologies. Unlike many forms of SOA platforms, such as RESTful or SOAP, GraphQL was designed with both API consumers and developers in mind. With its powerful schema-based development approach, you’ll find you can expose data quickly and securely without having to worry if the exposed properties align with each consumer. Why may you ask? GraphQL is essentially a query language for API’s allowing consumers to choose which properties they’ll receive. Add in enhanced features like caching, schema stitching, or subscriptions you can quickly provide consumers with powerful features like record filtering or pagination / sorting, which significantly improves usability / consumption.

It’s all About the Schema

The schema is the root of everything with GraphQL. It breaks API interactions into three simple actions: queries, subscriptions, and mutations. This is a logical approach because we either need to read / watch data or change it. This simple division of duties takes all the guessing out of making the right call based on HTTP request methods and endpoints.

When using REST API’s, we usually have an accompanying Swagger, RAML, or WSDL metadata file that helps us understand the API we’re about to consume. This setup type usually requires additional developer time spent to keep documentation current and expose said documents with your clients / consumers. Hence, they know how to interact with your API. GraphQL schema’s by contrast, are self-documenting, strongly typed, and can be retrieved with a simple retrospective call against the API. So, what’s the big deal? Imagine the time savings with every new client application or mobile app you make. Or imagine making constant changes and revisions to an API that you would no longer have to document and publish explicitly. You may find you’re sending unused data points for a mobile application, leading to payload bloat. With each client’s ability to pick and choose their payload, we essentially have full CRUD APIs and Facilitation APIs in one. We won’t have to spend time creating a “mobile-friendly” version of each API to reduce the payload to maximize connection efficiency. This approach also allows us to easily add additional fields without a need to create new versions of an API as the new field won’t change any existing payloads.

Why Developers Love it

We’ve talked about the schema and the framework’s flexibility, but what does the adoption look like with the developer community? We can’t get the benefit without an easy adoption. Luckily, GraphQL provides such a simple approach to APIs that most developers love making it a part of their application stack!

A few features that stand out:

Strongly Typed: Have you ever coded a page only to eventually hit a Null reference? We all have. In those cases, we tend to be become paranoid and find ourselves doing unnecessary Null checks to ensure our code doesn’t blow up. It would be nice not to have to worry about that. With GraphQL, we know, based on the return types, what fields are nullable, and we can quickly add checks for those we know may not always have value.
JSON: GraphQL is JSON in and out. We send it JSON objects to filter and mutate, and we receive JSON as objects and arrays. JSON plays nicely with most modern languages, makes it easier to form wiring, and with query control, we get precise response payloads.
Community Support: While GraphQL may not be the most widely used API format at this moment, it has one of the most passionate communities with a lot of solid development support features. These include Schema Browsers, ready to use JavaScript clients, and quick-start components such as Hasura, which can reverse-engineer a PostgreSQL database and provide a fully functional graph API in minutes.
Subscriptions: We mentioned subscriptions briefly at the start, and while they’re mostly equivalent to queries, they serve one primary purpose. And that is auto data refreshes when underlying objects change. This is hugely advantageous for certain types of features where transactional data is updated continuously, and the data presented needs to reflect those changes. Think chatbot, analytics charts, etc.

Integrate Legacy Systems

GraphQL can integrate with your legacy systems seamlessly. It can wrap your existing RESTful, SOAP APIs and allow them to be accessible through its endpoints. Also, it can combine legacy data with new GraphQL resources or other legacy resources. This is hugely advantageous to developers because it allows you to begin using GraphQL without requiring an entire rewrite of the existing systems.

What are you Waiting for?

GraphQL isn’t new. It’s been around for many years, but it’s still new to many developers. If you haven’t worked on a project with it, we highly recommend it. GraphQL provides a rich ecosystem of tools, patterns, and best practices to enable teams of all sizes and skill levels. The flexibility of designing queries to fit your views and the ability to see all types and actions available through a Schema Browser makes teams more effective and productive without needing external documentation. Queries written in a client tool like Insomnia or Postman can be copied & pasted into your project with predictable results.

At UDig, our teams have been building API’s for many years, but nothing was more eye-opening, enjoyable, and productivity inducing as our switch to GraphQL. Our developers are more independent. Our API writers can think in Schema Relationships without worrying about versions of API’s that compliment views to reduce payloads. We’re delivering faster with more flexibility than ever before.