Nullability in GraphQL unlocks improvements in resiliency, graceful UI degradation, frictionless user workflows, and other benefits

Whether you prefer “schema first” or “resolver first”, GraphQL development should definitely be “types first”. One aspect of planning your data types is nullability, and this is important to get right. Nullability in GraphQL is different than how we handle null values in other environments, like REST or gRPC APIs. You see, we expect a RESTful endpoint to either return an object, a list, or other piece(s) of data as a whole — or not at all. If a REST GET operation fails, we expect the entire request to have failed — not just a subset of the operation.

GraphQL is inherently different

However, that’s not how GraphQL rolls. It’s entirely acceptable and likely that most of your data graph will load successfully, except a small part will fail due to the composition of the many micro-services responsible for populating all of that data. When all of the fields in a type are marked as “non-nullable” (using the !), a failure can no longer occur gracefully.

Said differently, if any one non-nullable field defined in your type is ever null, or its resolver throws an exception, the entire query fails. Not cool.

Consider this example …

We’ve started a new schema for our Vrbo app, and have defined a VacationRental and its associated types. Notice how everything is non-nullable by default, a common yet problematic approach when creating a new schema:

Let’s look at some of the problems this can lead to, and how we might better approach this initial schema creation …

Nullability is important to users

Kinda. They don’t care what it is, but it definitely affects their experience. Using nullable fields in your GraphQL projections means that when (not if) one or more parts of a screen fail, the rest of the screen may remain perfectly usable (yay!). But it’s a real problem if a less-critical portion of your data becomes unavailable due to a database outage, or a hiccup in your network, or a good ol’ act of God, and suddenly your user cannot be successful in achieving whatever one thing was most important to them on that screen.

Allow your screen to fail gracefully

Think about our vacation rental example …

If the owner of a vacation rental property is viewing their Property Editor screen, attempting to write an impactful headline and illustrative description for their new property, it’s not important that something small like an Inbox Notification shown in the Top Nav Bar fails. If the Notifications service is down for 20 mins, and the inboxNotifications field returns null, the rest of the query still succeeds and the Owner can accomplish their primary goal on that screen — playfully word-smithing the content that guests will see when viewing their property.

Let’s update our example to allow inboxNotifications to have a null value, meaning if the Notifications service fails, the property owner can still edit their listing:

If your entire query fails, your UI can’t allow your user to have at least some success, or to be shown a specific and helpful message. When the entire query fails, all you can do is tell your user “Something broke, please try again” (even though you and I both know it won’t work when they try again).

Users care that your app is resilient, and nullable fields on your GraphQL types allow portions of your screen to fail gracefully while the rest of the screen remains usable.

Think of nullable fields as error boundaries, which will likely align with the API service boundaries behind your GraphQL server 🤔

Offer a frictionless user flow

If we want to allow a property owner to incrementally save their progress while listing their gorgeous home for rent, we can’t require every field to be populated at once. If a user first enters the listing title, then description, then address — and each time the screen auto-saves their progress for a frictionless experience and a saved backup in case their computer and/or network starts acting up — then you must allow those fields to be nullable.

Let’s update our VacationRental type to be more flexible and enable that user experience …

Now our typedef allows each field within our UI to be saved automatically as a user progresses through their workflow. Neato!

Describe your domain

Nullable fields in GraphQL should be used to accurately describe the business domain rules. For example, a company may require all owners to enter their name, email, and phone so that guests can reach them.

But perhaps you don’t require every owner to have a twitterHandle, because not everybody twitters. Let’s make that change, too:

Facebook’s best practices

In the GraphQL docs, the Best Practices page advises you begin defining types using nullable fields, and only later might you decide to indicate specific fields as non-nullable when such a guarantee can actually be made. But by default, allowing fields to be nullable improves the resiliency of the larger data graph:

“… in a GraphQL type system, every field is nullable by default. This is because there are many things which can go awry in a networked service backed by databases and other services. A database could go down, an asynchronous action could fail, an exception could be thrown.”

Yes, this might result in more null checks throughout your system, but you should probably be doing some of those anyway !

If you’re working with JavaScript, things will get easier soon. Optional Chaining is at Stage-2 in TC39, and there’s a Babel plugin if you just can’t wait (some languages already have this feature, like Swift). And it’s much more painful trying to ensure that never once will any of your field data return null. (Good luck with that, though!)

But non-nullable is good, too!

Yup, it sure is! Let’s talk about when it’s a good idea to begin your schema design with non-nullable fields, because I’m definitely not preaching we should “nullable all the things!”

SOME TYPES DON’T MAKE SENSE WITHOUT REQUIRED FIELDS

Let’s look at the GeoLocation and Notification types in the example …

A GeoLocation makes no sense at all with just a latitude, or just a longitude. And a Notification within your system will always contain a timestamp and a message, because it’s enforced in your nice type-safe backend. The amount of a Price isn’t enough to generate a transaction if you don’t know what currency is to be used.

There’s no reason to ever allow nulls in those fields, so we’ll leave those marked as non-nullable. This reduces your cyclomatic complexity, which is important to the amount of null checks (read: lines of code) you must write in your front-end to avoid errors, as well as the number of unit tests you must write to achieve good test coverage.

This increased verbosity, complexity and required tests is a great reason to always ask yourself, “Is it worth it to allow this field to actually be null?” 🤷‍♂️

Go faster, and go backwards

When you’re spinning up a new data graph, your project is probably evolving quickly with a team of people. Leaving GraphQL fields nullable frees you up to iterate faster, be flexible, and allow you to defer decisions about your data until the last responsible moment.

Some of those decisions are harder to ⌘-Z than others. Beginning your data graph with nullable type fields, then later on converting some fields to non-nullable is backwards-compatible. However, when you mark those fields as non-nullable from the start, it’s a lot more difficult to make them nullable later on, as there may be code in the wild that calls that data without null checks and your apps could crash.

This might be the opposite of how your input parameters work, but you’re probably still safer to start off with nullable parameters and enforce those required fields in your code if necessary.

The final schema

So after much pondering, we’ve made some important decisions about our schema. Here’s what I had as the first version in my head, is it what you would’ve done?

Interested in solving complex, consumer-facing problems like this? Join us, and together, let’s bring the world within reach.

Nullability in GraphQL was originally published in Expedia Group Tech Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

Developers love to launch. It’s the culmination of weeks or months of work (if it’s years, you better be building an operating system) and the public is about to see what you’ve created. But it’s far from the end of your big release.

And if you’re juggling multiple projects, it’s tempting to wipe your hands clean after a site or app launches, and change your full focus to a new project. This is especially true when your team has truly done their best to maintain quality throughout the design and development process. You’ve thought of everything, tested with a small group of trusted users, and you only had so much time booked in the calendar, so you call it done.

pressLaunchButton();
onToNextProject();

What may be missing from your schedule is the “.1 release”.

A recent launch of an intranet portal is a great example. Our team did a fantastic job of innovating during the design & dev phases, as well as leveraging some cool new interaction methods and technical integrations (new to us anyway!) We estimated our development time reasonably well, and set the expectations with ourselves that we were delivering a 1.0 release, and we’d come back soon to address all of the experiential things that we knew users would have to tolerate for a bit (e.g., slower-than-ideal authentication/authorization on first load) while we focused on a different project with a totally different set of end users.

That was almost 6 months ago.

The problem is that because there was another high-priority project waiting in the queue, we consciously skipped the .1 release of the previous project. But the .1 release is the release where you monitor the application and the experience your users are having, and respond to their needs quickly. The .1 release is where we make good on all those IOUs we made while disclaiming “we must deliver something now, we committed to a date and we’ll get in trouble if we miss it”, and that each of their individual needs will be addressed in the next version. This is all fairly standard and valid, as long as you actually plan the time in your project schedule necessary to listen to your users and improve their experience.

When we constantly deliver at 100% (or greater), we don’t give ourselves enough buffer. Not just setting aside time to mitigate known and unknown risks throughout a project (the latter is frequently forgotten), but buffer to sit back and listen after a major release. We should have confidence that we couldn’t possibly have gotten everything perfect for every user, so allocating time to ensure that even their smaller needs are addressed before we move on to another project is imperative. The small things may determine whether or not a user finds value in your product, and a healthy user growth curve is supported by happy users.

The .1 Release is the “Listening Release”

Once you’ve launched that first or other major release, celebrate the win! Get a good night’s sleep. Then come to work and just listen. Certainly we’ve all built multiple feedback loops into our applications, right? We have New Relic analytics for our server performance, exceptions logged to a database for analysis, a feedback form and forums for users to contact us … but why did we build all of that into our app in the first place? We did so to enable us to know more about how our app is doing, and more importantly how our users are doing, so that we could take action where necessary. Listening but failing to follow up with improvements and fixes right away could potentially be worse than not listening at all because you’ve set users’ expectations incorrectly.

There are very objective reasons for dedicating time and effort to listen to, and fully understand, your users. Such as meeting expectations better, and being more efficient by avoiding rework. But there’s also an emotional component to the exercise itself — it builds trust with users, and demonstrates a genuine empathy for their needs.

Failing to Listen Guarantees You Are Forever Playing Catch-Up

Most of us don’t get to set all of our own priorities — they are dictated or influenced by customers, managers, colleagues, holiday shopping seasons, and such. We have multiple projects and products in our workshop, and we constantly switch context to whatever is most important right now. And while there are some environments where that works well, context-switching in software development is expensive in terms of time. The constant drumbeat of “deliver, deliver, deliver” often means that important phases of an application’s life cycle get omitted.

Think about who’s priorities we’re catering to when the consequences of delivering later versus earlier are greater than the consequences of not delivering the best experience to our users. (Hint: it’s not your users’ priorities you’re optimizing for …)

When we don’t schedule the time in the project plan to follow up with a .1 release, users feel unheard and abandoned. Sometimes for a long time. Yes, you hit your deadline, and you’re on to put out the next fire (because every project is the most important project, right?) However, we’ve only served our own priorities at the expense of ignoring those of our users. And as long as we continue to release without listening, and without following up immediately with a “listening release”, we are guaranteed to always have a growing backlog and worse, a growing number of frustrated users.

As Ron Swanson said, “Never half-ass two things. Whole-ass one thing.”

A Better Experience for Everyone

And I do mean everyone! The best way to ensure that what you’ve created is actually improving the lives people (because at our core, makers of all disciplines want to build things that impact people) is to release your best work, then take the time to listen to users, set correct expectations, and address their needs as best as you can. Don’t declare “mission accomplished” and move on before your users are happy. This builds trust with your users, which is a very necessary component to user adoption.

Knowing the triple constraint exists in project management, increasing quality isn’t free. But deciding early on that the definition of success is based on a level of quality and user acceptance and not just the delivery date, and that you will spend the additional time and cost required to make users happy will make building and using your product a much more enjoyable experience for everyone.

Just remember who you are ultimately designing for, and spend most of your time serving their needs and priorities.

(Featured image courtesy of Flickr.com/Rumpleteaser)

Originally published at grantnorwood.com on November 28, 2015.