Best Practices
Introduction
Interactions with BigCommerce APIs can be orchestrated in your own applications in any number of ways to achieve your needs. With the freedom of this paradigm comes the possibility of implementing poor practices that unnecessarily tax the APIs, run into rate limits, or exhibit poor performance in your own apps when they are deployed at scale.
In this section, we’ll address some of the most important best practices to keep in mind when developing with BigCommerce APIs.
Rate Limits
It’s important to be aware of the API rate limits that apply to your BigCommerce plan. Even plans with no hard limits can still potentially run into 429 Too Many Requests error responses if excessive requests tax physical infrastructure limitations.
Designing your applications efficiently will avoid approaching rate limits.
See more details about rate limits in the BigCommerce documentation.
Primary Design Principles
The design of an application utilizing BigCommerce web APIs should conform to three primary principles. The specific practices we’ll cover next serve one or more of these primary goals.
- Efficiency: Make as few API calls as possible, requesting only the data your application needs.
- Mindfulness: There should be a distinct purpose for each API call.
- Responsiveness: An application should respond appropriately and shift tactics when encountering errors in API call responses.
Good Practices
Avoid Polling
Avoid making interval-based fetches for data just to check for updates. This creates potential for the majority of such API requests to be unnecessary when data hasn’t changed. There are usually more efficient alternative strategies.
Webhooks are an effective tool for responding to data changes that occur in BigCommerce.
Polling at intervals in shopper-facing front-ends can be particularly detrimental, as the effect can be multiplied across a high volume of users. It’s typically a best practice to perform new fetches of data only in response to specific user interactions.
Cache Data
For data fetches that are likely to be needed frequently, implement a caching strategy to reuse response data rather than repeatedly requesting it. This is effective in situations where data is unlikely to change frequently, or when a few minutes of stale data is not detrimental.
Use Batch-Based Strategies
It’s far more efficient to make a single API request to fetch many resources than one request for each resource.
Many resources also have bulk endpoints for update operations as well; consider whether such endpoints can be used in your application to reduce the volume of update requests.
Distribute Load with Asynchronous Actions
When integrations might potentially experience peak periods of high volume, implement a strategy to spread the API calls over time with asynchronous queues.
Make Update Calls Based on Actions
API calls that create or update data are more resource intensive than others. Make sure that such requests are made in response to appropriate inciting actions. For example, if you routinely sync customer data from an external system into BigCommerce, avoid updating all records on a scheduled basis, since this may result in many unnecessary updates. Instead, respond to changes to records in the external system by queuing specific updates to BigCommerce.
Respond to Rate Limit Statuses Appropriately
When API requests hit rate limits, BigCommerce responds with appropriate status codes and other headers giving details about the rate limiting window. Applications should intelligently handle this response information with delay-based retries.
Write Durable Code
Avoid brittle code that makes unnecessary assumptions about API schema. As an example, note that BigCommerce may make non-breaking changes to API endpoints without notice, such as introducing new fields in a response. Application code should not break or leak memory if new fields are returned.
Stay Up to Date
BigCommerce publishes release notes to notify the development community of changes to the platform, including when endpoints or features are deprecated. Make sure to check these release notes on a regular basis to keep your applications working effectively with the web APIs and tools.
You can also find a list of deprecations and sunsets in the BigCommerce documentation.
