Bridging the Gap Between APIs and UX: Designing for Simplicity Amid Complexity

“Trust me, we’re going to build something cool, everyone’s going to love it, and we’ll be able to replace all the other services once we release it.”

My principal staff engineer couldn’t hide his excitement. But what exactly is this service? I had no clue. With limited knowledge and only a handful of people understanding the existing service, I realized the challenge wasn’t just design—it was translating a complex, backend concept into an intuitive experience for both technical and non-technical users.

My principal engineer had been driving the concept solo for over a year now. A full year of head start, my nerves were starting to bubble. Would I be able to catch up and have any input at this point?

“A technical person would understand it.”

That was the most common response I received when I managed to find someone with knowledge of the service (which was like 3 people throughout the entire company)—”that’s just how it is.” It’s designed and built for a developer, and as long as they understand it, we’re good.

Moment of Clarity

I find the best approach to tackle a redesign, is to learn about the old or current one first—understand what worked well and what didn’t. After trying to investigate our current service and running into walls with technical documentation, I felt lost.

It wasn’t until our CXO pointed me to our developer advocate at the time—James, did I start to see past the mist. James was amazing, breaking down the concepts for me, guiding me to realize the real challenge—the narrative in how we describe our product offering.

This was the turning point that defined the direction of my approach. If I, as the lead designer, took such a long time to understand the concept, and no one on my team was able to easily communicate and explain what we’re trying to achieve, that was the problem.

“Even if I know how to do something with the APIs, if I have a easy UI I can leverage, I’d go with that any day.”

Robert, a FE engineer from another team once said that when we were collaborating on another feature. And that stuck with me. 100%. Just because something is technical in nature and targeted towards a technical audience doesn’t mean the UI has to mimic that complexity. And even if we had to surface complexity, we needed to make that complexity comprehensible and manageable.

Breakthrough and Inspiration

Looking at our competitors and their offerings in tackling custom endpoints, I came to one conclusion—this type of feature is still commonly perceived as BaaS. It’s so “backend” that no wonder no one cared about the “UX”. As long as it caters to the developers, right?

I didn’t want to accept this as the only way of building such a feature.

My research shifted from competitors to functional analysis with inspirations from products like Google Forms and Airtable. Seeing how simple their data entry was, inspired a new direction—prioritizing intuitiveness over technicality.

I started collecting all the different data types we wanted to offer: strings, numbers, boolean, floats, enums etc. Initially, I didn’t know what a string meant, what the conditions were, or that you can customize it to display in a date or time format. Nor did I know that a boolean meant true/false or yes/no or that it can be displayed as a toggle. Sure, a technical person would get that without an itch, but that also doesn’t guarantee the frontend output, does it? Setting up a boolean field doesn’t necessarily result in the frontend UI to display a toggle. It could equally mean a check box, or yes/no selections.

We should strip the technical terminologies and aim for a more intuitive UI that directly reflects how our customers intended to display their data.

Scope and Technical Challenges

After identifying the gap, I brought my team in on my ideas and approach. It took a few moments for them to connect the dots (understandable, as I was pitching a direction that was never considered or even on our radar). It was generally well received, especially with my exploration into Airtable, I illustrated how we can help our merchandisers better visualize and manage their data. (Technical users are responsible for the build, but business users would be consuming the build and use it to manage their day to day needs.)

To get to this simplicity, we needed a more robust backend—something we couldn’t fully achieve within our release timeline. We’re also not looking to bridge the merchandiser experience for now, so making it super intuitive isn’t a priority as “a technical person would already know the complexities”.

Our backend team wanted to keep our architecture as simple as possible. We didn’t know the shape of data each of our customers would have and wouldn’t know or be able to cater to all the different needs. We wouldn’t know what information needed to be prioritized or excluded. Simply put, we had to keep our service flexible.

But the nature of this feature is complex. And choosing to keep the backend simple, means we have to shift all that complexity to the UI and frontend.

Flexibility and customization are key capabilities, and neither is something we can offer in our early releases. After discussions, we opted for a backend simple solution for our initial launch, while planning for future iterations to support more data types and complex validations.

Usability Refinements

One of the things we don’t do very well is allowing our dashboard to be ‘smart’. Half of our UI is form based for customers to input and capture their data. Our limited backend meant we couldn’t provide immediate form validation, leading users to repeat trial-and-error cycles. With most forms consisting of over 40 input fields, this can get quite frustrating. With the absence of immediate system feedback, users are heavily taxed with the mental effort to double check their work or know how to operate the system well.

We had to get creative. Since a lot of the validation fields are dependent on the type of data the user is creating, we can streamline the validation requirements. Displaying only relevant options, allows for better comprehension. And in restricting certain actions upfront, reduces cognitive load on the users and minimizes opportunity for error.

Simplifying the Concept

One of the key pain points of this entire initiative is the concept. It took me a few months to grasp. And every time I shared my ideas or progress, I had to explain the concept all over again. It isn’t something people can easily comprehend. Especially to the non-technical crowd. It became a nightmare of sorts when trying to get feedback and input from other teams.

We extended our team’s involvement beyond the product trio after the first quarter. Even when they had high level knowledge, onboarding the rest of the team was tougher than expected. Our principal engineer ran a few kickoff sessions, all met with blank stares, silence and confusion—clearly not all BE engineers can easily understand this concept either.

I took on the responsibility to communicate the gaps. This was the first time I felt any sense of accomplishment with this challenging project. I was now able to communicate and allow others to understand and onboard better than I did.

Along with my product manager, we knew this was something we had to address. How can we market and sell this product if people can’t even understand what it is? If we, the team who’s building it, don’t even understand it ourselves? I set out on a mission to make this concept as easy as possible.

One of the frustration point I discovered was that we had muddled two distinct concepts into one—extending data on top of an existing service and creating custom endpoints. This created a lot of confusion.

Separating the two concepts and offerings, allows us to create more narrative and guidance to help our users understand what we offer and what they can do.

Reflection

My engineers always emphasized that this particular feature is intended for technical users. But I’ve always wondered—what is the goal of our customers and their business? What are they looking to achieve? Isn’t the end goal still to address a business goal? Is the technical user really our primary persona? Or are they just a means and a bridge to help out a business user achieve their goals? Granted, a business user may not be able to manage such a configuration heavy task, but at the end of the day, isn’t it still for them to be able to manage the data they needed? In a lot of cases, some times, our customers are quite business oriented and doesn’t have great technical support. They just have no choice but to find experts to handle these tasks that are beyond their expertise.

What we should do, is to bridge the gap, giving technical users an intuitive tool to empower business users. Despite tailoring our initial release for developers, the team agreed on my proposal to transform the service into a self-service tool that business users could eventually manage independently.

The concept is actually quite simple—build anything. I like to use the lego analogy. We offer all the building blocks, you can pick and choose whichever ones you like and build anything your heart desires.