Ready for GraphQL: Step Two, Planning a Technical Evaluation

Okay. You keep hearing about GraphQL, and you’re getting the feeling you need to take a closer look. Maybe you’re not ready to dive in, but you are interested in at least sizing up the pool…

Coque, Luxembourg.

For review: Why GraphQL is worth getting ready for:
1. It improves developer productivity, communication, and morale; especially potent for distributed teams

2. GraphQL makes prototyping and iterating apps against complex data structures unprecedentedly easy and fast

3. The possibilities for microservices orchestration are huge

4. Data designed for application users using GraphQL is the best-designed data

5. Early adopters of GraphQL include many, or even most, of the major technology companies in the world

Hello again!¹

This is Part Two of our series on preparing an organization for evaluating and potentially adopting GraphQL:

1. Doing Research
2. GraphQL Technical Evaluation
3. GraphQL as a Data Management Approach
4. Thinking about GraphQL as a Practice
5. Final Evaluation

(Unlinked items aren’t written yet.)

As we mentioned at the top of the series, we’re assuming that you are managing a technical team or department or legion, or otherwise helping to guide an organization’s progress toward a brave new world of semantic APIs. Obviously, with that assumption there is a lot of wiggle room, and you may or may not be interested in the details of the technology to a code point level.

We’ll also assume that you and your colleagues are planning, building, or maintaining one or more software applications, probably web-fronted.

How long will it take to do a technical evaluation?

A team of 2 or 3 experienced people should be able to capably demonstrate all the features of GraphQL, including an addition or two from the ecosystem, in about 10 weeks. That’s 2 dedicated weeks of thrashing and learning, and 8 weeks of prototyping. Adding team members above 2 or 3 would allow the prototype to shoot for higher delivery objectives.

Multiply these estimates by your local bureaucracy variable — we know some tech startups that would be a 0.8, and some very large pharmas that would range between 2.5 and 3.5. You’ll know the lay of the land where you are.

Asking the right questions before the evaluation

Even if your core team feels it has all the answers, it’s extremely constructive to think through, answer, and put on paper the types of questions you need the technology evaluation to answer.

What would be the benefit of implementing GraphQL?

Since you are planning an evaluation, you don’t necessarily have to prove anything at this point. On the other hand, it’s nice to go into an experiment with a working hypothesis. “We expect that by using GraphQL to facilitate communication between our applications, we will increase our delivery speed, increase consistency across projects, and reduce errors between applications.” That might be sufficient; ideally, the hypothesis can succeed if just one of the assertions would be good enough to float the whole initiative.

All of this will plug into a Cost-Benefit Analysis or other similar decision-making vehicle at some point, but that vehicle will typically be consumed primarily by management, not your team. For the purposes of your technical evaluation, it will be good to be ready to promote the benefits of the evaluation with the engineers and implementers who will be affected.

What approach works best for us?

Basically; fast or slow; a little or a lot? We have worked with a number of organizations where even the most blindingly obvious changes could only happen incrementally. Better incrementally than not at all. The good news here is that GraphQL can easily be rolled out incrementally or even alongside legacy APIs. For many large organizations this seems like a rational approach.

What are the gotchas that can ruin our day?

More formally, what are the risks associated with adopting GraphQL? These break down into two general buckets; the risks everyone knows about and the risks that would only be true for your organization.

As of the time of writing this, the public risks to pay attention to are security, scalability, and code stability of ecosystem libraries.

Security and scalability are concerns for every project, so there’s sort of an additive inverse effect with GraphQL (it will be incurring security and scalability concerns that are probably of similar magnitude to whatever technology it displaces.) Not that they aren’t important — but they can be planned for, and there are some really smart people in the ecosystem cranking on just these problems.

The code stability is a little bit trickier, as it’s a variable that fluctuates widely over time. At this stage in the maturity of most of the ecosystem’s platforms, it would be safe to build some extra weeks of float into a GraphQL prototyping plan in order to deal with issues where an unsupported function or missing library completely blocks progress. If the team’s normal padding is 20 percent, maybe call it 33 percent for now. For almost any implementation methodology, our favorite way to handle float is with “stretch” goals. There should be plenty of those for a GraphQL conversion or new project.

Your private risks may involve other technology projects that are competing for resources and attention, budget and organization changes, or possibly the reliance on third party software that can’t be adopted. These are a few example considerations; the possibilities are widespread.

Can we standardize on a specific implementation or set of implementations? Do we even need to?

During the evaluation stage of GraphQL, preserving flexibility is probably worth quite a bit to the ultimate success of the initiative. This is doubly true with an ecosystem that is a bit of a moving target. The goal of the evaluation is to learn about the options and gather enough information to begin thinking about standardizing.

What vendors and frameworks will work for us?

Choosing GraphQL almost certainly means choosing a number of ecosystem servers, libraries, and even development tools. We’ll discuss that below. Again, the goal is to learn enough to begin to answer the question. Your next step after a technology evaluation might be a vendor selection process — this evaluation should make your team smart for that one.

Who in our organization needs to know/care?

An oddly tricky one! GraphQL could affect most teams in a large technical organization, even business analysts. In fact, since no organization works in a vacuum, it almost surely will have some sort of impact even if your team decides against using it internally. It’s a good idea to identify the people who would be affected in either situation, and prepare to come out of this technical evaluation phase with an idea of how they will be affected. This will be a worthy slide or three in the Powerpoint at the end of the project or pilot.

Thinking About a Pilot

In this discussion, we are mixing the terms “evaluation projects” and “pilots” for basically the same thing — a small technical application or single iteration of a larger one that incorporates GraphQL. While the exact term for this depends on your organization’s vernacular, choosing the right application in any case will need to be keyed to the situation on the ground.

Piloting GraphQL with a project in planning

If your team is planning to build a project in the next few months, we would absolutely recommend adding GraphQL to the roadmap if the project fits a few criteria:

• Not mission-critical
• Performance demands will be moderate (ideally non-zero)
• Web interface will be needed and there are subject matter experts to help flesh it out

To be fair, there are some very large, high-profile, high-performance projects out in the world today that use GraphQL. We would think twice about “learning on the job” at the same time as executing one, however. It’s possible your team includes one or more colleagues with the background to ensure the project does not get hung up.

A deeper issue is the subject matter expert connection. GraphQL absolutely shines in teams of mixed technical and product people, as it facilitates super rapid translation from ideas and designs to domain objects and relationships. Piloting GraphQL without business folks in the mix would be a missed opportunity.

A terrific story about changing up APIs on a product that is under development is told in the back-end-front-end pattern article by Phil Calcado, who describes a major overhaul involving GraphQL for the products from Soundcloud.

Piloting GraphQL if you are already building something

If your team is already working on a project to build a services-driven (or microservices-driven) application, we would consider the context of adding in a GraphQL API carefully. GraphQL can easily live side-by-side with existing middle tiers. In many cases, there would be nothing particularly harrowing about adding the API to the server, and we expect that the conformational process of working through an additional step of Schema generation and validation would actively help more projects than it would hurt. An issue may come up in client development since the generation of GraphQL objects would possibly represent a big change to front-end teams’ workflows. A second client or external API goal would be more reasonable cases where GraphQL could productively join the party.

This is totally achievable, but may take some additional effort and planning. Adding GraphQL to an existing project can be especially worth the extra effort in cases where integrating services or data from a variety of sources threatens to bog down the ongoing effort.

Piloting GraphQL while maintaining a production system

What is the percentage of enterprise applications that were planned to have a public API, only to be pushed out into production without one?

50? 90?

At any rate, it’s a big number. Here’s your chance to add a great API to a system that houses a load of valuable data and goes untapped by the organization despite nonetheless.

Piloting GraphQL with nothing in the works yet

The sky is basically the limit here, but of course the end goal is typically a successful pilot that actually helps users right out of the gate. We initially going to put in something about “Only run GraphQL pilots on Javascript projects, since most of the documentation lives there.” This might be true-ish, but honestly if your team is heavily into Rust or Haskell, it might be capable of figuring things out as it goes.

If you are “hunting” for a showcase for GraphQL, we would recommend a small enough project to be actively embraced by business users and useful even as a first-iteration release. We’ve seen real potential in small “glue” projects that sit on top of a number of systems that would be otherwise troublesome to bridge. (For example, mixing ERP and public data into a dashboard. Having a schema design stage for this is going to be mandatory. It’s easy to slice the ingestion of data into project phases, and the schema and application built may have a chance of punching its way out of pilot and into production.)

Mixing in another technology, especially a front-end framework, might actually be advantageous to help sell the project to technical teams — doing so probably wouldn’t harm the evaluation process for GraphQL.

Thinking about Evaluating GraphQL and Technology Stacks

In a perfect world with infinite time and resources, a technology review would ideally just focus on “vanilla” GraphQL. If your team exists in that world or close enough to it, GraphQL + Node/Express + Javascript (or GraphQL + Graphene + Django for Pythoners) would be a good way to fully comprehend how relationships manifest between server and client packages.

For the rest of the world, the pressure will be there to get to a showcaseable prototype quickly. Your team will typically want to use a packaged server as well as some client extras like a front-end framework with plugins to speed application development. An ancillary benefit of working with more complete tools and stacks will be a much broader base of documentation to work with; especially from the vendors.

Three major vendors to look at in particular are Apollo, Prisma, and Hasura. A blow-by-blow comparison is beyond the scope of this article, but here are a few points:

• They aren’t all selling the same thing.
• Apollo GraphQL provides a very “standard” GraphQL package that works with about everything out there and is very focused on the middleware itself. As a trailblazing GraphQL company, Apollo takes a lot of flack; some of it deserved. Still, most pilots should at least consider Apollo.
• Hasura is aimed at the front-end, with a focus on hyper-rapid application development that seems terrific for pilots if you can live with some “on rails” (not those ) decisions by the provider.
• Meanwhile Prisma aims at the back end, pitching ORM replacements for connecting middleware to common RDBs using GraphQL — the promise being: hey, now you are controlling your front-end and back-end with the same schema artifacts. This prospect excites us.
• Each of these vendors has a Community offering and is easy to get started working with. There are other vendors, of course — especially if you are reading this article more than two weeks after it goes up. We think we would stick to these three in a tech evaluation unless we had a really good reason not to.
• The vendors overlap but aren’t mutually exclusive. You probably wouldn’t want to try all three in one demo project.
• There are several open source projects out there that kind-of/sort-of compete with the vendors. The first one to check out is GraphQLNexus, which is focused on making code generation far easier. Nexus would possibly stand in for at least one of the vendors above. Apollo is also part of a broader “stack” framework called GRANDstack, which is worth a look if React is on the table and your team could tolerate Neo4j (at least for a pilot.)

That is not an exhaustive list of vendor notes, but it is a start. To summarize: for sure check out the vendors, and most Technology Evals will probably use/require one or more of them. Be prepared to keep GraphQL but switch implementations after a pilot (and put that possibility in writing up front!)

What will adding GraphQL cost?

Obviously it’s difficult to put together a price tag for a technology change that will make a number of subtle differences to how the team works for a while. Rather than stretching for an exact number, it might be better to focus on a methodology for investigating and estimating both costs and benefits.

In the spirit of developing that methodology for the sake of a project proposal, consider especially that GraphQL will almost certainly add raw costs in terms of person-time, not only for delivering a working project but also in exchange for delivering an overall higher-quality product with a more adaptable, flexible interface between layers. The time you spend on schema development and discussions with business might also be abnormally high, although again these probably equate to higher overall product quality. These added costs can more or less be traced to the added time/effort “padding” we suggested above.

Working with GraphQL will also add to the risk component of project costs, especially if your entire team is new to the language.

On the other hand, implementing GraphQL will surely displace other accepted standard application development processes. Importantly, this should be subtracted out from the raw added costs, as well as the raw risk of just working with technology in general. Almost every new technical project incurs some risks and GraphQL is not likely to be an edge case in this area.

For our next article in the series, we’ll take a look at the longer-term implications on the technical impacts of GraphQL for data development and models in the organization. Until then, we hope you’ve got a good start on running down information and planning a strategy for a GraphQL successful pilot for your team.

Notes

1. We recognize that this is not how Medium necessarily works.

(Updated 16 October 2019 with a link to the Calcado article)

Photo of Coque from visitluxembourg.com. Coque is an amazing place to take the kids for diving practice!

This post was generated using MarkdownToMedium.