Sponsor: Do you build complex software systems? See how NServiceBus makes it easier to design, build, and manage software systems that use message queues to achieve loose coupling. Get started for free.
Debugging and troubleshooting are a big part of a developer’s day-to-day. Because of this, when designing your APIs, provide good API error messages as well as guide developers down a path of success and makes it easier for them to understand issues when they need to troubleshoot.
YouTube
Check out my YouTube channel, where I post all kinds of content accompanying my posts, including this video showing everything in this post.
Meaningful Error Messages
When designing an API, it’s important to consider the experience of the developers who will consume it. A well-structured error message can serve as a guiding light, illuminating the path to a solution when things go wrong. For instance, consider a situation where an API call fails.
As an example, here’s NServiceBus. When you configure it at the application startup, it immediately tells you something isn’t supported but explicitly what.
A vague message like “not supported” does little to help the developer understand the issue. However, in this case, because of a good exception message, I know that the outbox isn’t supported when using the persistence I was trying to use. I either need to use another persistence or disable the outbox feature, and it’s even showing me how.
In practice, many developers have encountered APIs that return cryptic error messages, leading to endless debugging sessions. The rarity of meaningful error messages in the industry highlights the need for improvement. Providing clear and actionable error messages is one of the keys to a great developer experience.
Be Explicit
Another aspect of creating a good developer experience is being explicit regarding the intent of your code. Let’s consider a common scenario in data retrieval. When querying a collection, developers often have the option to use methods like “Single” or “First.” While some may argue that using “First” is faster, it can lead to hidden data issues.
If the intent is to ensure that only one item matches the criteria, using “Single” provides a meaningful exception when the assumption fails. This explicitness not only aids in debugging but also ensures that developers are aware of potential data integrity issues.
For example, if a developer writes code that uses “First” instead of “Single,” they may inadvertently hide underlying data problems. In contrast, using “Single” will raise an exception if more than one item is found, prompting the developer to address the data issue immediately. This practice of being explicit helps in maintaining the integrity of the data and guides developers in writing more robust code.
Check out my post on Single() or First()? Understand the Abstractions you use!
Guiding Developers Down the Path to Success
When designing APIs, it’s helpful to guide developers toward success by anticipating potential pitfalls. One approach is to avoid throwing exceptions that developers must catch.
Exceptions are like hidden land mines. When you’re writing client code calling into a library, do you know under all situations it might throw? Probably not. And there are likely situations where you want to handle certain failures, to which you end up using a try/catch to control flow.
Instead, return an option type that reflects the outcome of the operation. For example, when retrieving an order, instead of throwing an exception if the order is not found, return an “Option” that can either hold a value or indicate absence.
This way our calling code can handle if there is a result or not.
This method simplifies the calling code and makes it more intuitive. For instance, the order controller can check the returned option and respond accordingly, returning a 404 status if the order is not found. By avoiding exceptions, we don’t have to guess and manage if there are landmines. There aren’t. Our client returns explicitly on success.
API Error Messages for a GOOD Developer Experience
It’s amazing how often developers don’t read error messages. I get it; many developers have run into useless error messages that weren’t helpful at all, so they’re reluctant to put in much effort.
However, designing APIs that provide meaningful error messages can really improve the developer experience. By focusing on being clear and explicit, you can really help a developer succeed when they call your code. Lead the down the path to success.
Join CodeOpinon!
Developer-level members of my Patreon or YouTube channel get access to a private Discord server to chat with other developers about Software Architecture and Design and access to source code for any working demo application I post on my blog or YouTube. Check out my Patreon or YouTube Membership for more info.