Advancing API-first with BigCommerce Widgets
When bringing a product to market, you have a decision to make.
You can build and launch the product, get it into the hands of your users, and then later surface an API to allow the ecosystem to extend it. Or, you can take the API-first approach.
API-first development means just that — building the API before the full product feature. Rather than designing a UI and then later developing an API to support it, building the public API first allows you to think beyond a narrow set of use cases and get new functionality into the hands of the ecosystem faster.
At BigCommerce, we recently released the Widgets API, putting the API-first approach into practice.
The Widgets API is a foundational step towards providing native visual content merchandising capabilities in BigCommerce. From the beginning, that’s what we’ve been building towards. But our first step has been to build the API that will support our own product and make it available to our developer ecosystem.
Over the course of the last year, we worked with a group of partners, developers, and merchants who beta-tested the Widgets API before its release in March. We’ve been encouraged by the solutions that are already being used in production today, and the experience has illustrated the advantages of taking an API-first approach.
In this post, we’ll talk with one of those beta participants, Brand Collective, to hear how they leveraged the Widgets API during the beta to build an in-house tool that allows their staff to create complex content management workflows, without touching code. We’ll also hear from two BigCommerce Product Managers, Juan Ruiz, who led the Widgets project, and Nathan Booker, Senior Product Manager overseeing API and Platform, about the role of API-first development in releasing the Widgets API as well as what we learned along the way.
Lighthouse Customer: Brand Collective
Jamie Kerr is the Senior Web Developer at Brand Collective, a company whose portfolio spans a number of owned and licensed brands. As part of the ecommerce division within the company, Jamie’s development team operates like an in-house agency, building custom solutions, including internal tools that web administrators use to manage the day-to-day operations of stores.
During the Widgets API beta, Brand Collective were early adopters and innovators. Jamie and his team built an addition to their ecommerce toolkit that allows web admins to create and place content blocks in templates, without editing HTML or CSS.
“One of the key requirements was that the system would be flexible enough for our administrators to be able to do what they need to do within a widget, without us having to write a specific widget template for every single use case,” Jamie says. To accomplish that, Jamie designs widgets to be as configurable as possible, through a UI that allows the user to choose from a menu of different fields. Because the Widgets API separates the structure of the widget from its content, a single widget template can be reused in different template locations, with different content, providing a flexible and modular design system. The app UI provides a form with widget configuration options, allowing web admins to combine content and design elements within the template.
Brand Collective’s app also includes functionality to schedule content block visibility. During the app’s widget configuration step, users can specify start and end dates, and those values are pushed to the widget markup. From there, a client-side script controls the visibility on the storefront based on the widget’s start and expiration dates.
For Brand Collective, having early access to the Widgets API meant the ability to custom build a solution that fit their business needs. “I think giving people the flexibility of having an API that allows them to put their own solutions together is a really big convenience,” Jamie says. “When accommodating the enterprise business and the fact that we require at least a certain degree of flexibility with these things, the API should have enough give and take for us to be able to put in our own solutions.”
During the beta, Brand Collective provided feedback to the BigCommerce product team that has and continues to shape the direction of the API. The takeaway is that Brand Collective was able to build a UI purpose-built to their workflow, allowing them to develop a tool that precisely fits their needs — and they were able to do it on their timeline. With access to the Widgets API, Brand Collective leapt ahead of the typical product development process to get a solution into the hands of their users quickly.
The Benefits of API-First Development
An API-first approach has advantages for stakeholders on all sides of the development process. Building an API before a feature’s UI has implications for the way product and engineering teams think about solving problems, and there are advantages for developers and end users as well. Using the Widgets API as a case study, we’ll take a look at four benefits that illustrate why an API-first approach is a flexible and powerful way to build a new feature.
1. Broader design mentality.
When examining an API-first approach, it helps to step back and consider the alternative. When you first design the UI that you want to build and then later decide what APIs you’ll need to support it, at that point, “You’re often thinking quite narrowly about that API,” Nathan Booker says.
Conversely, beginning with API design opens the discussion to a much wider range of use cases that can be solved for. “You’re inherently thinking a bit broader at the beginning, which gets you thinking the correct way earlier in the process,” Nathan says. This prevents having to make revisions and changes to the API later on to support a wider range of use cases, because the first iteration of the API was tightly coupled to your own UI.
Juan agrees: “That was the success of the Widgets API approach, because we front-loaded a lot of the work of thinking about those use cases and provided an API that allows so many flavors of content to be added. It’s very flexible and open.”
2. Faster time to value.
Faster time to value doesn’t necessarily equate to the length of time that it takes to ship the full product feature. In fact, given the way designing API-first shapes the kind of up-front planning a product team needs to do, it might actually extend the time to ship a product, although you’ll have a more flexible and robust product in the long run.
Rather, it’s all about the time that it takes to start providing value to your users — and when you’re running ahead with an API, you do begin providing value as early as possible in the product development process. With early access to the API that powers a feature, partners and developers are equipped to start building tools and applications around that API without being tied to the timetable for the full product launch. When you make the API available at the earliest stages of the product, developers are free to build the specific solution that they need today.
3. Unlock the 20% use cases.
Which users are you building your product feature for? If you said ‘All of them,’ that’s the wrong answer. A product that tries to be all things to all users will always miss the mark. Nathan Booker proposes that you should cater to use cases that meet the needs of 80% of the user base and enable the partner community to solve for the 20%, more niche use cases.
“By giving our partners the ability to run in parallel with us from the beginning, we can have a more effective launch, because we can say ‘Hey, here’s the point and click feature for the 80%,’ but maybe you have some specific needs around apparel or B2B.” By providing an API to the partner community early on, “there are already solutions to those 20% use cases from the beginning, even if they’re not built natively.”
4. Validate assumptions.
Building API-first gives you an early checkpoint for validating whether you’re building a product that actually solves the problem that you set out to solve.
“If you get feedback that your API isn’t solving the problem,” Nathan says, “then slapping a UI on top of it isn’t going to solve it any better. Building the API first and gathering feedback is an early checkpoint for evaluating whether the problem is being solved on a low level; later, you can focus on making it easier to use, intuitive, and point-and-click.”
During the beta, participants began using the Widgets API in production at an early stage, and we were able to learn from the successes and feedback of the community. This allowed us to affirm that we were on the right track and establish guideposts for the kinds of enhancements that would benefit the community in future iterations of the product.
Takeaways and Lessons Learned
The Widgets API beta was long-running — about 12 months. This was due in part to the fact that an API-first strategy is still tied to planning around the native feature. In order to know that the API is ready, you still have to come to an agreement about what the native capabilities will look like and be sure that the API is going to support them. “When we landed on this strategy with API-first, it was because we were able to align the pieces and strategy for our native visual merchandising solution,” Juan says. “We knew, okay, these pieces are going to come in, and this is more or less when, and there’s nothing that will block us from shipping this.”
It was also helpful to look at the historical data from the beta to indicate when the API was ready to launch as a first phase. “Throughout the duration of the beta, participants were really leveraging the technology, really leveraging the API,” without having a native UI, Juan says. “That was a big indicator that helped to support this vision about going API first.”
Another consideration was that by the time the API beta period ended, the API contract with the developer community had been established. Any changes from that point forward need to be additive and can’t alter the behavior that developers have already built their applications around. That’s another reason why building API-first requires special consideration — updates directly affect the ecosystem, so it’s important to communicate clearly and proceed knowing that changes have downstream effects.
Conclusion
Taking an API-first approach puts solutions into the hands of developers and partners at the earliest possible stage, unlocking the kinds of custom solutions that are essential to enterprise businesses. But API-first also has implications for product teams. Instead of designing around a narrow use case, from the beginning, product teams are thinking about the broadest application of a feature.
Nathan Booker explains the concept in terms of a Venn diagram:
“You have these overlapping circles, if you will, where you have the things that are possible, but require some effort. And then you have the things that we as a platform make point-and-click and kind of first party features where we do the whole thing end to end. Putting an API out there allows you to have a really big circle of things that are possible, and that allows you to choose which things you want to make easy over time. There are some use cases that we will probably never build into our software, there are some that we probably will, but maybe it’ll be a year from now. And in the meantime, people have a solution.”
Building on that expansive view, Juan envisions a future where the Widgets API could be used to power alternative visual merchandising tools. “With the success of this API, we’re also looking into aligning with our headless strategy. We’re interested in exploring even more use cases, use cases that we never even thought about in the beginning. Imagine we could have 3rd party page builders leveraging our Widget API, providing a full end to end visual merchandising that is not native to BigCommerce. We would like to see where we can take this.”
We’d like to give a huge thank you to Brand Collective for partnering with us during the Widgets API beta, and Jamie for sharing his story. Check out Brand Collective’s newest launch, Superdry.com.au, powered by BigCommerce and the Widgets API.
Let us know what you think about building API-first. Join the conversation in the comments below or find us on Twitter @BigCommerceDevs.
