Authors: Andrew Larkin, Jiecheng Dong, Kevin Phan, Yeong Sil Yoon

A short introduction to GraphQL:

GraphQL has redefined how APIs and services handle data fetching since its release in 2015. By exposing a strongly typed schema and allowing clients to specify exactly what data they need in queries, GraphQL provides greater flexibility compared to traditional REST conventions where servers define fixed endpoints. This shift enables more seamless data interactions between front-end and back-end, as well as within backend systems.

Our Problem Space:

Realizing the full benefits of GraphQL’s flexibility requires overcoming some challenges. GraphQL’s capability to fetch precise data can also result in clients requesting excessive data, both inadvertently through inexperience and malice. This over-fetching can greatly degrade API performance and security, especially when GraphQL is exposed publicly. Under-fetching data can also be an issue, requiring extra roundtrips. Managing these vulnerabilities is essential to delivering performant and robust GraphQL implementations.

Introducing GleiphQL:

GleiphQL is a developer tool tailored to solve some of these challenges with GraphQL. By offering a rate-limiting library with complexity analysis and an opt-in monitoring tool, GleiphQL looks to offer a means to secure GraphQL endpoints and allow both internal introspection and security against external malicious queries. Here is an overview of key features:

Rate Limiting: Prevent server overload by defining rate-limits for individual users accessing a given endpoint.

Complexity Analysis: GleiphQL employs an efficient algorithm to swiftly compute complexity scores pre-query execution based on user-defined costs and list-sizes exposed in schema definition through @cost and @paginationLimit directives.

Live Metric Visualizer: GleiphQL’s user-friendly web app lets developers track query data with live updates and robust visuals based on collected metrics.

GleiphQL has taken significant inspiration from IBM’s original paper on a more robust solution to analyzing query complexity.

How to get started:

Getting acquainted with GleiphQL is straightforward. Follow the link to our repo that provides documentation on getting set-up. This section will give an overview on the most salient points of user configuration to help you get an idea of what you’ll need to do to onboard the tool. The bulk of the user setup will be in defining an @cost directive on relevant fields and arguments as well as augmenting lists with an @paginationLimit directive.

This can be done by adding the definitions to your existing directive definitions, and exposing the relevant cost metadata on a field-by-field basis. An example SDL implementation is as follows, note that the polymorphic interface or union types should not be supplied with a cost:

directive @cost(value: Int) on FIELD_DEFINITION | ARGUMENT_DEFINITION
directive @paginationLimit(value: Int) on FIELD_DEFINITION

type Author {
id: ID! @cost(value: 1)
name: String @cost(value: 200)
books: [Book] @cost(value: 3)
}

type Book {
id: ID! @cost(value: 1)
title: String @cost(value: 2)
author: Author @cost(value: 3)
}

union SearchResult = Author | Book

type Query {
authors: [Author] @cost(value: 2)
books(limit: Int @cost(value:10)): [Book] @cost(value: 2) @paginationLimit(value: 5)
search(term: String): [SearchResult] @paginationLimit(value: 10)
}

If you want to monitor a specific interaction, you can assign costs only to certain fields. If you want a precise granular view you can freely assign whatever cost to any number of fields. It should be noted that these directives serve solely to expose metadata for the complexity analysis. @cost is defined by user preference and can be informed by whatever metrics or evaluations you would like to use. @paginationLimit does not actually bound the list returns, it only exposes an upper limit for the analysis to assume as the worst-case scenario for list complexity calculations.

Fields not provided with @cost will assume a cost of 1, while lists not provided with an @paginationLimit will have their limits informed by the configuration below:

const apolloRateLimitConfig: ApolloConfig = {
  complexityLimit: 3000,
  paginationLimit: 10,
  refillTime: 300000, // 5 minutes
  refillAmount: 1000,
  redis: false,
  maxDepth: 1
}

For further details on configuring GleiphQL’s rate limiting and monitoring capabilities, please refer to our repo. This article provided a short overview, but the documentation covers the full configuration process including setting complexity limits, pagination limits, refill rates, and more.

How to Get Involved:

We invite you to join us in enhancing GleiphQL. Our goals include developing post-query analysis solutions, expanding visual metrics for better insights, designing a graphical user interface for simplified developer configurations and API control, and releasing a tool that helps the user quickly define a reasonable set of costs for their schema fields.

Summary:

GleiphQL, in collaboration with OSLabs, offers complexity analysis, rate limiting and visualization of relevant metrics. It’s a valuable tool that enables developers to bolster server security and ensure performance is not compromised. Consider implementing GleiphQL to harness the power of GraphQL while safeguarding your applications.

Connect with GleiphQL:

Contribute to our product on Github

GleiphQL || LinkedIn

Jiecheng Dong || Github || LinkedIn

Andrew Larkin || Github || LinkedIn

Kevin Phan || Github || LinkedIn

Yeong Sil Yoon || Github || LinkedIn