GraphQL has become a ubiquitous technology in the modern landscape. Offering substantial power, flexibility, and extensibility, GraphQL is highly customizable. This customization may seem at first blush to fly in the face of API governance, but does it really? What’s it like to actually apply API governance to GraphQL, and is it easier to govern than REST? Let’s take a look!

A Brief Review

Before we dive into GraphQL, let’s briefly look at governance as a concept to see where GraphQL stands in context. Simply put, API governance is the set of policies, procedures, standards, and practices that an organization can set to help govern the consistency, stability, and usability of APIs within an organization. In other words, governance describes how your APIs should function and provides a way to ensure they follow these guidelines.

Why Governance?

API governance gives an organization greater control over the entire API lifecycle, ensuring that standards of usability, extensibility, stability, and security are adhered to. When properly deployed, governance policies can be a technical mirror of the business and purpose use case that drives the success of the organization. For example, if your service is designed to provide high-value functionality to diverse users in a secure environment, a proper governance policy can ensure that all the elements of that statement are supported with the correct underlying systems, processes, and resources.

Notably, governance is a good way to set standards across the board within an organization. API governance sets an understanding of what is “ok” within the ecosystem and, by doing so, guides the creation of new projects without requiring consistent gates and pressure points.

What Makes it Difficult?

Governance can be challenging because it’s often viewed as diametrically opposed to rapid iteration. API development often occurs at 100% throttle, and API governance is like a firm hand just to the side, pulling back and saying, “Wait one second.” For this reason, governance is often challenging to implement for hypergrowth-focused businesses.

Another reality is that API governance is often implemented with a “one-size-fits-all” approach. However, exceptions often necessitate changes for teams working on diverse products or even products targeting different use cases, undermining the very purpose of API governance.

API governance also requires some process oversight. While API governance often starts quite strong, new iteration, development, and rapid prototyping can create an environment where these rules are bypassed “just this once,” tempting developers to simply ignore them. This then introduces new managerial gates and processes that undermine the main benefit of API governance, turning the invisible guiding hand into a type of Big Brother.

GraphQL vs REST

Comparing REST to GraphQL is quite interesting. While REST is a standard paradigm, GraphQL is a query language. To make this comparison fair, we should consider what the typical REST implementation looks like compared to GraphQL.

GraphQL and REST share quite a lot of similarities. They are stateless, designed around resource representations, and align with a client-server model. Their data structures are often similar at the basic level, sharing support for the same hypermedia-driven models of data connectedness. For this reason, REST and GraphQL are often bundled into the same solution class.

When you look under the hood, however, GraphQL has some unique features that make it easier to govern than REST.

GraphQL is Well-Defined and Structured

GraphQL is strongly typed and has a declarative schema definition system. To be strongly typed means the system has very specific types of data enforced, and each piece of data within the implementation must adhere to the type it aligns with. Alongside a declarative schema definition, this means that GraphQL APIs are well-defined at the schema level, allowing for substantial enforcement of policy through the schema itself.

Additionally, GraphQL leverages a structure that can best be summarized as a graph. This graph represents the interconnected pieces of the singular microservice and contains the relationships of the other microservices it connects to. Because this relationship is so well-structured at the micro and macro level, API governance can be well-enforced at a granular and top-down level.

In essence, GraphQL can become mostly well-governed simply by being well-designed from the get-go. In this case, the schema acts as a contract between the server and client, providing a clear, robust, and controlled interaction paradigm, and deviations from this schema definition don’t create aberrant API inclusions — they just get rejected and denied.

GraphQL Presents a Unified Point of Governance

Another unique feature of GraphQL is how endpoints behave. In RESTful design, collecting data across multiple queries and systems requires multiple queries and combinatory efforts. This multi-point querying introduces substantial complexity but also requires implementing more governance policies.

GraphQL, on the other hand, typically operates via a single point of entry before routing to internal systems or serving data from combinatory sources. This ultimately means that GraphQL governance only has to care about a small subset of endpoints compared to the more numerous and complex endpoint collections required under REST.

GraphQL is Strongly Introspective

While REST has some systems that promote introspection, GraphQL is uniquely effective at surfacing the understanding of its schema, data, and functions to the client. This introspection makes it easier to deploy governance — in GraphQL, the system wants to be understood, so governance across the system is given a clear map from the get-go.

Considerations

With all of that in mind, it is important to remember that while GraphQL is generally easier to govern than REST due to its strong typing, declarative schemas, and robust internal design paradigm, some considerations make governance different than under REST.

GraphQL is highly flexible, but this flexibility means that you need to put thought into exactly where this governance occurs. When anyone can request structured data in a preferred format, you either need to apply strict control to protect that data, which has some performance implications, or you need to proactively design the data to not introduce the risk.

GraphQL also introduces complexity the larger it gets. While it grants great efficiency, more complex schemas mean governance grows in complexity as well, making for a very heavy system.

Best Practices For Governing GraphQL

With this in mind, what best practices can we apply when building API governance for GraphQL? Here are some tips for bringing a healthy governance model to GraphQL.

Schema is King

When it comes to GraphQL, building a good schema is the name of the game. API governance can be easier to implement in GraphQL, but it’s also easier to mess it up if you create a poorly defined and poorly thought-out schema. Accordingly, defining clear naming conventions, types, field controls, relationships, and more will go a long way towards ensuring your API governance is effective.

To do this right, make sure you are using the right tools. Effective designs and effective schemas require standards and tools that have been proven, are fully understood, and are leveraged to their full potential.

Plan for the Long-Term

Your schema-based API governance is only successful if it adheres to business use cases. Business use cases change, though, so how can one ensure you can change to new business requirements without losing the benefit of schema-driven governance?

Plan for the long term! When building out your schema, make sure that each part is designed to accommodate changes and new modalities. Plan your communication modalities to ensure proper deprecation and sunsetting, and use hypermedia and meta context to provide alternatives and updates where appropriate. Ensure that your schema can shift to new needs, and you will ensure that your API governance policy stays relevant to the use case.

Leverage Federation

GraphQL federation is a great way to retain a consistent experience between multiple schemas. Federation creates a sort of “gateway of schemas,” connecting services together and pointing where each schema lives within the data flow. This leverages metadata to provide greater functionality and continuity between services.

From a management point of view, it’s possible that having developers working on their own subgraphs could create a situation where their services are compliant with governance rules while generating name collisions and other similar issues. Accordingly, have a central source of truth and ensure that your teams cross-communicate. Leverage documentation and internal portals to ensure that teams create subgraphs that match the schema without conflicting with other development efforts. This will help save you a lot of headaches in the long term and will lead to a much healthier system.

Create a Culture of Compliance and Communication

Part of an API governance strategy is getting everyone on board. A culture of teamwork is vital for securing APIs and deploying governance effectively at scale. Accordingly, it’s not just enough to define the governance policies — you must also sell them to your team and clarify why they’re important. You must champion governance, and your policies must be sensible and well-designed.

As part of this, your governance guidelines should be replicable without high friction. You should provide tooling and systems to verify compliance throughout the lifecycle to ensure your governance policies are adhered to. Still, you should also be creating a culture in which your internal developers understand the importance of compliance and the end goal you are trying to attain.

GraphQL provides a substantial amount of customizability for the end user — accordingly, this culture of compliance is important for securing long-term success.

Conclusion

Governing GraphQL is easy to do right — but it’s also easy to do wrong! Simply following the best practices in this piece can help you establish a strong culture and schema to deploy API governance at scale effectively and efficiently while using GraphQL.

How are you implementing API governance or management for GraphQL? Did we miss any best practices? Let us know in the comments below!