As our software-based business has gotten deeper into the GraphQL API ecosystem, we’ve picked up some valuable best practices along the way. The open source query language is the future of APIs, but getting it to hum (and hum at scale) takes some strategizing.

Juxtaposed with aging REST API technology, GraphQL provides transformative advantages by empowering applications to collect all necessary data via a single API request, and to directly control that data rather than relying on server connectivity.

Those key differences allow development teams to deliver more stable applications, and do so faster and with fewer difficulties. Organizations enlisting GraphQL can vastly improve the quality of both their applications and their developer experience (as our own developers can attest).

But GraphQL adoption does include a few pitfalls that can cause implementations to come up short of their goals. Namely, GraphQL scalability, visibility, and security aren’t givens. They require well-thought-through strategies that are aligned with current best practices.

Here’s what we’ve learned. These strategies should help make your GraphQL API modernization journey a smoother one.

Support GraphQL scalability from the start

While GraphQL is simple enough for a few developers to quickly get a server going, building the stable and scalable implementation that your company will require to unlock its bigger benefits takes more of an investment. It’s crucial that leadership fully buy in, commit, and support the GraphQL implementation, ideally from day one.

With GraphQL, everything is easier if you get it right the first time. Many companies make the strategic error of allowing GraphQL to grow wild within their organizations, leaving it barely supported and poorly secured. Inevitably, some stakeholders will believe that if a GraphQL deployment has yet to scale, it doesn’t yet require enterprise-grade support. However, from operational and security perspectives, that approach means leaving GraphQL as a technology outpost, wielded by a handful of developers and vulnerable to being overrun by performance issues and unwanted infiltrations.

When GraphQL use does pass whatever threshold those strategists have in mind, and it’s time to bring those brownfield GraphQL deployments into line with best practices, teams find that undoing those poor foundational decisions is like picking raisins out of a fully baked cake. In an all-too-common example, developers operating without foresight often hard-code access controls into GraphQL servers and resolvers out of convenience. Doing so hampers performance and security at scale, until teams go back and painstakingly remove that code.

The far better strategy is to fully commit to GraphQL and implement it properly from the start. Introducing a greenfield GraphQL environment founded on best practices is a gift to your future organization. It’s easier to operate and secure both now and going forward, it delivers immediate dividends for the effort, and it makes scaling and reaching roadmap goals much easier and faster.

Support GraphQL with deep analytics

Organizations make a mistake when they team traditional monitoring with GraphQL: standard approaches miss out on valuable query insights and business intelligence. Tools contoured to GraphQL-specific behaviors are necessary to collect deep analytics and equally deep insights into server health and issues that arise at the query level.

If your organization has adopted GraphQL but has yet to put effective visibility tooling in place, you’re in a race against time to do so before your implementation scales to rely on a federated graph. With a federated graph, APIs expose a single data graph that combines (and obscures) multiple subgraphs.

Platform teams equipped with only traditional tools will lack the visibility to understand which subgraph is associated with what traffic. Performance issues and wasted resources will become highly challenging to address, hidden behind this federated architecture. This is why it’s crucial to enable full visibility into GraphQL resources, data, and workloads as part of your organization’s deployment—from the start, if possible.

Have a GraphQL-specific security strategy

GraphQL has a security profile all its own, and requires a security approach able to neutralize threats specifically designed to exploit GraphQL vulnerabilities. Organizations that rely on traditional API and web application gateways cannot effectively secure API code, identify traffic anomalies that may represent threat activity, or stand up secure and efficient access controls. To secure GraphQL, organizations must instead enlist modern methods capable of discovering GraphQL traffic and providing deep visibility that enables real-time security responses.

I’ll give an example of a security incident we recently experienced. Over a recent weekend, we received an alert that an abnormally high volume of requests was coming through our GraphQL layer. Fortunately, prior to this incident we had deployed the Inigo GraphQL management platform to protect our production GraphQL servers. We used our application performance monitoring (APM) metrics to identify the time range and resolve service to the load in question. With the Inigo security and analytics tools, we could identify the user and workspace causing the traffic.

The “threat” turned out to be a legitimate user, which gave us all a huge sigh of relief. This event also turned out to be valuable in unearthing a part of our app that needed optimization. Without our GraphQL-specific security strategy, however, we wouldn’t have had the visibility to understand which user was impacted by this issue, or how to resolve it so decisively.

Make sure everyone is on the same page

Within organizations adopting GraphQL, it’s all too easy for developers to end up out in front in pursuing GraphQL’s advantages—but for some stakeholders to ride the brakes when it comes to introducing proper enterprise-grade support. GraphQL champions within your organization must address these tendencies and rally the broader team to move forward as one.

Supporting a newly deployed GraphQL implementation with the right strategies and best practices unlocks tremendous potential for greater operational efficiency and a leading developer experience. The recipe for API modernization success is introducing customized management, analytics, and security alongside GraphQL deployments.

Will Guedes is the Co-founder and CTO at Yottled, which provides small, service-based businesses with software tools for customer booking, CRM, payments, and more.

—

New Tech Forum provides a venue to explore and discuss emerging enterprise technology in unprecedented depth and breadth. The selection is subjective, based on our pick of the technologies we believe to be important and of greatest interest to InfoWorld readers. InfoWorld does not accept marketing collateral for publication and reserves the right to edit all contributed content. Send all inquiries to newtechforum@infoworld.com.