API Best Practices
Keep your integration up to date
BigCommerce frequently enhances its core product and is actively enhancing REST endpoints, as well as expanding the graphs accessible to our GraphQL APIs. Using the latest information lets you update your app to take advantage of the most current resources. You also position your app or implementation to provide a user experience consistent with what merchants see in their BigCommerce store control panel. To stay up to date, bookmark our changelog.
Anticipate changes to BigCommerce APIs
At BigCommerce, we make a distinction between "breaking" and "non-breaking" changes.
In most cases, we will give advance notice in our developer changelog when we make any of the following "breaking" changes. However, we will make breaking changes without warning to alpha and beta endpoints and graph nodes, or when analytics indicate that an endpoint has no traffic for three months.
Examples of breaking changes include:
- Removing fields from API responses
- Changing the data type of request or response fields
- Changing the structure of request or response objects
- Adding new required fields to
POST
andPUT
request bodies - Removing endpoints
We will push "non-breaking" changes to the code base without warning as part of our normal development.
Examples of non-breaking changes include:
- Adding new fields to
GET
request responses - Adding new optional fields to
POST
andPUT
request bodies - Adding new endpoints
We encourage you to write robust, resilient code that will not break or leak memory if an endpoint begins to return additional fields.
Use webhooks to listen for changes
To keep your app's data up to date, webhooks provide a great alternative to periodic API polling. Use a store-level or app-level API account to register and subscribe to webhook-enabled events relevant to your app.
When an event your app is listening for occurs, BigCommerce sends a payload with a few identifying details relevant to the event. See a list of webhook events and their payloads. Use the payload data points to make subsequent API requests for more details.
Avoid polling the Storefront Cart API
Client-side applications should avoid polling the REST Storefront Cart API on interval. Millions of browsers could poll this API at any given time, causing a significant load increase to BigCommerce's servers. We may take action against a store using this practice to prevent service interruptions to other stores.
As an alternative, consider using a server-side app to subscribe to cart webhook events, then query the Storefront Cart API only as a response to user input. Storing cart information in the browser cache is an alternative method for updating cart information across browser tabs. You may also be interested in the growing list of events available to native storefronts with our Open Data Layer enabled.
Thread API requests
You can use threaded requests in order to quickly update information in an API. Threaded requests allow you to send multiple requests at one time. They can come from a different open connection or multiple requests to the same resource.
The BigCommerce Ruby API client (opens in a new tab) is thread-safe. It satisfies both the need for multiple threads to access the same shared data and the need for only one thread to access a shared piece of data at any given time. This design pattern can reduce the total time that your app requires to complete a series of requests.
Looking for more information on handling requests? Continue with API rate limits to learn about our best practices.
Resources
API platform
- Platform Limits (Help Center) (opens in a new tab)
- API Terms of Service (bigcommerce.com) (opens in a new tab)
- Filtering Requests
- API Status Codes
- About Our API: Response Headers
- API rate limits
- Guide to API Accountswebhook events and their payloads
- Changelog
Correlating requests
When building a headless storefront, it's best practice to group related requests using the X-Correlation-Id
header. This indicates to BigCommerce's infrastructure that an API call is part of a larger operation, and helps us track the handoff from request to request as the operation moves through our servers. To learn more about the header, see our list of request headers. For an example and a more in-depth explanation, see the Introduction to Headless Commerce.
Resources
Related articles
API references and clients
- API Reference
- REST Storefront Cart API
- Upsert price list records
- BigCommerce Ruby API client (GitHub) (opens in a new tab)