How Workarounds Reveal the True Needs of Your API Consumers

Workarounds are clever, but less than ideal solutions to problems that shouldn’t really exist. In the world of APIs, an example of this might be scraping an application’s frontend to make up for endpoints that don’t exist.

At first sight, workarounds may seem like a bad thing. However, if you look a little deeper, you’ll see that workarounds actually provide invaluable insight into what consumers need from your APIs and how they’re using them. In this article, we’re going to discuss why you should care about workarounds. We’ll examine how they were used to improve a major eCommerce checkout experience, and how you can effectively manage them in your ecosystem.

This post is based on a session given by Karen White, Developer Advocate at BigCommerce, at our 2019 Austin API Summit. Watch the full talk below and view slides here.

Workarounds and The Texas Exit

Karen defines workarounds as “solutions that technically accomplish [a task], but in a less than straightforward way.” In other words, workarounds are indeed solutions (hey — isn’t anything that works a valid solution?), but they’re by no means the most elegant or long-lasting solutions.

An example of a workaround would be when an API doesn’t provide data in the context you need, so you’re forced to reverse engineer the code and repurpose endpoints to get your hands on some extra data. It works, but it ain’t pretty.

As Karen astutely points out, developers are problem solvers. They’ll find a way to do what they want to do, regardless of how painful it is. The result may not be the greatest solution — heck, the developers probably aren’t proud of it themselves — but it solves the problem.

Nathan Booker, a colleague at BigCommerce, has his own metaphor for workarounds: the Texas Exit; that is to say, “the act of driving across the unpaved grassy area that separates the highway from frontage road, without the use of an exit ramp.”

Why Should We Care about Workarounds?

While you can look at someone pulling a Texas Exit and think “wow, what an impatient jerk”, there’s a second side to the story. Ultimately, the driver tearing across the grass had some kind of problem — the traffic was too slow, they wanted to get to the gas station on the other side, or they were late for dinner — and they solved it for themselves.

From a user experience lens, if ten people are pulling this maneuver every day, perhaps that’s a sign you should build an exit ramp there. The lesson?

A workaround is trying to tell you something.

It’s the evidence of workarounds — the tire tracks on the grass — that tell you a better solution is needed. Unfortunately, this feedback is harder to get ahold of in the digital world, since there are no tire tracks to look for. And since this cunning problem solver has already fixed their own problem, they’re probably not going to stop to tell you about the issue.

Karen says that for every one developer who gets in touch about an issue, ten more of them hack together a workaround.

What’s Wrong with Workarounds?

At first glance, workarounds are great — they solve the problem for the time being. Unfortunately, they tend to cause headaches (for everyone involved) later down the road.

For the problem solvers, workarounds are always a fragile solution. They’re difficult to adapt and scale, and they make it hard to onboard new developers (who now have to get to grips with a hacky solution). When the core product is updated, workarounds often fall apart.

For product teams, workarounds aren’t on the radar. As such, team members end up making changes that break developers’ solutions without even realizing.

The BigCommerce Checkout (Case Study)

Karen was kind enough to share a case study of how BigCommerce identified and managed the use of workarounds in their platform’s checkout functionality.

Previously, the BigCommerce checkout was well locked-down. It was a single-page, Angular application with hidden source code, that consumed internal APIs with no documentation.

Because it was so difficult to do so, developers didn’t customize the BigCommerce checkout — or so they thought…

Of course, developers found all sorts of ways to achieve the desired effect. As an aside, Karen says this is to their credit; ultimately, they found a way to extract more value out of the platform and thus provide more value for their mutual customers.

This was a problem for two reasons. Firstly, Karen acknowledges that BigCommerce should have been providing a better alternative anyway; developers shouldn’t have had to resort to a workaround for something that has a perfectly good business case. Secondly, this led to a lot of checkout pages breaking whenever the engineering team made an update to the internal APIs, thus losing money for the customers.

To solve this, BigCommerce proceeded with building a public API for the checkout page that can be called client-side. It exposes all of the checkout’s business logic, like the cart functionality, the calculations, and the handling of payments.

They also built a JavaScript SDK to interact with that checkout API. This meant developers now had a nice wrapper with predefined methods they could use to move the shopper through the checkout process, allowing them to build and customize the frontend however they pleased.

It also allowed developers to introduce their own logic for custom features, such as picking up purchased items in store.

Finally, BigCommerce changed the native checkout experience so it would use that same public checkout API. This way, internal engineers had to be more cautious of how their changes could affect the final product.

Overall, Karen is extremely positive about the results of this change, and so are developers. By creating a contract of sorts between internal developers and the developer community, BigCommerce had built stability and trust, and given developers a path to creating the solutions they need.

How to Manage Workarounds Effectively

Karen was kind enough to give us some tips for managing workarounds in our own developer ecosystems.

Gather Feedback

The first step in managing workarounds is being able to identify them. As discussed earlier, since the creators of workarounds have already — by definition — solved their own problems, it’s unlikely they’ll stop to tell you about the issue.

So how do you identify workarounds before inadvertently breaking them?

Karen suggests leveraging all of your communication channels to see how your APIs are used in the wild. Whether it’s Stack Overflow, Slack, or your proprietary community, these channels are often the places developers come to access questions when they’re stuck.

Just by monitoring these channels, you can find out what issues developers are facing, and what workarounds they’re having to create.

Build Relations With Developers

Aside from that, Karen recommends building a strong working relationship with other internal teams who work closely with your community, such as API support teams. By talking to support agents, sales engineers, and solutions architects, you can see what issues and workarounds they’re coming across.

Finally, engage with community members — especially those pushing the bounds of your platform — and get them to give you that insider insight. Be direct and ask them questions like “What would you like a cleaner solution for?” and “What workflows could be more efficient?”, thereby identifying the issues that do have a workaround, not just the totally-unresolved ones.

Don’t Get Complacent

When it comes to actually solving issues and negating the need for workarounds, Karen’s big piece of advice is not to get complacent.

While workarounds are often ingenious solutions, they tend to build up technical debt, or — worse yet — break. As a result, you shouldn’t get complacent about workarounds, allowing them to become official, go-to solutions.

As Karen jokes, you can open a can of tuna by rubbing it against a cinder block. Sure, you’ll get the tuna out of the can, but at some point you’ve got to buy a can opener…

Make sure you tackle issues and their workarounds as they appear. You might think that they’re less of a priority, since they have a temporary solution, but it’s important to recognize that workarounds are ultimately just bandaids.

Final Thoughts

As you can see, workarounds are an effective way to see how API consumers are really using your services. Although they can often fly under the radar, it’s important to catch and fix them before you inadvertently break developers’ solutions with internal updates. Karen offers up some great advice for doing so, following her experience with plenty of workarounds in the BigCommerce checkout experience.