Versioning the BigCommerce API: A Look at What’s New with v3

Just like relationships, organisms, and opinions, APIs evolve. And even though we can broadly agree that change is good, that doesn’t mean it’s easy. There are multiple schools of thought on the best way to version APIs, and mobilizing users to update their integrations is a significant undertaking. The one thing people do seem to agree on is that versioning a REST API is a hard problem to solve.

At BigCommerce, there’s a lot of thought and planning that goes into API design and releasing a new major API version. We’re currently transitioning from our v2 API to v3, and in this post, we want to dive into some of the reasons we’re making the upgrade. We’ll discuss the complexity of versioning an API that processes millions of requests per day and get into the details of what’s new with v3.

When is API Versioning Necessary?

In simplest terms, it’s time to release a new API version number when a breaking change is introduced. API changes can either be backward compatible, meaning they don’t require modifications on the part of clients consuming the API, or non-backward compatible, meaning action would be required to avoid breaking integrations.

Backward compatible changes are typically additive. You might add a new endpoint to an API or a new optional field or query parameter to an existing endpoint. Developers who are already using the API can continue to process requests without upgrading their code.

Non-backward compatible changes, on the other hand, would require clients to make changes to the way they consume the API, or risk breaking apps and integrations. Examples of breaking changes include subtractive changes, or removing a resource or required field, or adding a new field that’s required. Other breaking changes include updates to the URI structure or data model.

Between major versions, most APIs accumulate small, non-breaking changes and bug fixes. Over time though, it can become apparent that a more substantial modernization is needed. The biggest driver in our decision to release version 3 of our API was improving efficiency and developer experience. In the process, we also redesigned the product data model to more closely align with standard patterns across the ecommerce industry, allowing our catalog to more easily integrate with third-party applications and support a greater number of complex use cases. These changes represented a substantial change to the API contract and would not have been possible without releasing a new major version of the API.

It’s inevitable that change will happen — without it, we wouldn’t have innovation. An API versioning strategy is one way to introduce change while providing a transition path for API users. In the next section, we’ll discuss a few of the challenges of versioning an API and how we’re addressing them.

Why API Versioning is a Tricky Problem

Once you’ve determined that you need to introduce a breaking change into your API, the next step is figuring out how you’ll release a new version and eventually deprecate the old one. But there are a few reasons why that process can be difficult to negotiate.

1. Getting visibility into client solutions.

Unlike other types of products, APIs don’t have well-defined use cases — the types of integrations and problems an API is called upon to solve can vary tremendously. API providers build APIs without knowing all of the use cases they will be applied to, and it can be exciting to see how APIs become a tool for innovation.

The flip side is that when it’s time to introduce a change to the API, you only have a partial view into how the API is being used. You might make the assumption that a change will be non-breaking, without anticipating that it is a breaking change for someone using your API in an unconventional way.

At BigCommerce, we track API usage metrics to gain an understanding of how our APIs are being used, and we make every effort to account for the edge cases and the less common implementations that we discover. We also keep our eyes and ears open — one of the biggest inputs into our API development process are the interviews and conversations we have directly with developers who work with our APIs.

2. Observing the contract.

An API contract is a specification that describes an API, most often in the form of a Swagger file. The goal of the API contract is to establish consistency among the internal teams who are building an API and to document an API’s expected behaviors for clients building API integrations. The spec file typically includes all of the requests a client can make to an API as well which fields are required and the expected response format. We can think of the API contract as not just a document that describes an API, but also as an agreement between the API creator and the client that defines the behavior developers can expect to build integrations around.

When making changes to an API, it’s important to understand the established behaviors of the API that developers rely upon. Any change that requires a substantial update to the contract becomes a candidate for versioning.

3. Handling deprecation.

Maintaining two different versions of an API at the same time is a less than ideal state to be in, and eventually it will be time to deprecate the old API version. At BigCommerce, our philosophy is to hold off on discontinuing services until we can demonstrate that usage has fallen below significant levels. We track usage by monitoring API calls across both old and new services.

During the period that we’re maintaining both services, the goal is to be proactive about communicating what’s happening while giving developers plenty of time to update integrations. It helps that developers who upgrade to v3 can expect significant improvements in performance and ease of use over previous versions.

What’s Changing with V3?

We’ve set the stage with some background on how we’re thinking about API versioning at BigCommerce, but now we’ll get into the specifics of what’s new with the latest version of our API. Our first v3 endpoint was released in 2016, and we’re continuing to build out v3 counterparts for all of our v2 resources. All new API resources released over the last few years — features like Cart API, Payments API, and Widgets — are exclusively available in v3.

1. URI versioning and MIME type.

The versioning scheme we’ve adopted identifies the API version in the URI path. In v2, the products endpoint is located at https://api.bigcommerce.com/stores/{store-hash}/v2/products while on v3, the endpoint is https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products.

The v3 version of the API exclusively supports JSON, whereas previous versions also supported XML for some endpoints.

2. The v3 Catalog data model.

The first endpoint we released in v3 was Catalog, which was no accident. Our desire to redesign the product data model was one of the biggest factors that led to the release of a new major API version. We based our redesign on feedback from both merchants and app developers. From merchants, we heard that features like option sets and rules were difficult to conceptualize and creating products required navigating through multi-screen workflows. From developers, we heard that creating products required too many API calls and the product data model was difficult to sync with third party systems.

We designed the v3 catalog model to address both concerns. One of the biggest transformations was the introduction of variants. In the v3 model, a variant is a sellable unit you can track inventory against — essentially, an item that sits on a shelf in a warehouse. A product might have multiple variants, for example, a t-shirt that comes in multiple sizes, or it might be a simple product that’s only available in a single configuration — in that case, the product would be represented as a single, base variant.

This might seem like a simple shift in thinking, but it’s a powerful one. When we think of variants as discrete physical units, we can assign qualities on the variant level that are useful to track — SKU codes, weight, dimensions, and price adjustments. In the v2 model, all of these attributes were tracked relative to the parent product. For example, in v2, the price of an XXL t-shirt might have had a rule that added $2 to the base product price of $10. In v3, we simply say that an XXL t-shirt is $12.

Another major change is the way options are assigned to products. In v2, a merchant would create options, like size and color, and group them into option sets which were assigned to products. In addition to being somewhat cumbersome, this also meant that options could be shared globally across the product catalog, which made it difficult to edit product choices across individual products. In v3, options are assigned directly to products, which makes it easier to reason about which variations belong to which product and also means you never need to worry about edits unintentionally affecting other products.

For more information on the difference between the v2 and v3 product data model, check out our developer documentation.

3. Efficient design.

Our v2 APIs separated subresources into distinct endpoints, which needed to be called individually. While this did follow RESTful API principles pretty faithfully, it also added a significant amount of overhead to common tasks like creating products.

Let’s imagine that we wanted to create a product using the v2 API. We’d need to make separate calls to create the product, add an image, create options, create an option set, add the option set to the product….that’s a lot of API calls just to create a single product. With the v3 API, creating a complex product takes one API call.

Another big win for efficiency is support for batched requests with PUT and POST operations. With v3, you can now create or update multiple resources with a single API call.

We’ve designed our v3 API to increase efficiency with GET operations as well. Our v3 endpoints support the use of ?include parameters to request subresources along with the parent resource. For example, you might request a product and include its variants, images, custom_fields, options, etc. in the response.

Another new feature in v3 is the meta object at the end of each response, which contains information about pagination. Our APIs return a max of 250 records at a time, which means that developers requesting more than 250 items need to paginate the collection and loop over each page. The old version didn’t return metadata on the total number of pages, so it was necessary to loop over pages until you simply ran out. With v3, you can know exactly how many pages there will be ahead of time.

What’s Next?

As of today, we’ve released v3 versions of our Catalog and Customers APIs, along with a host of new endpoints that are exclusively available in v3. Our next priority is releasing a v3 version of our Orders endpoint, which is currently available only on v2.

For developers whose integrations use our v2 Product and Customers APIs, we encourage you to upgrade to the v3 versions — you’ll be able to take advantage of all of our latest enhancements and performance improvements. As a rule of thumb, we recommend using the v3 version of a resource when it’s available, as with Products and Customers, and falling back to v2 for resources that don’t yet have a v3 counterpart, as with Orders. This means you may be calling both v2 and v3 endpoints within a single application.

Conclusion

API updates are a chance to reevaluate our approach and make performance improvements that help developers work more productively with our APIs. By splitting off changes into a new major version, developers can transition integrations more gracefully and control how and when to begin using the upgraded version of the API.

With version 3 of the BigCommerce API, we’re standardizing the catalog data model and making requests more efficient by orders of magnitude. Our v3 improvements are also heavily focused on developer experience, and that means your feedback is crucial. If you have insights you’d like to share, you can get in touch with our developer experience team by commenting on this post or tweeting @BigCommerceDevs. And be sure to keep up with the latest API updates here on the Developer Blog and by following our Changelog.