Starting BigCommerce Development: Introduction to APIs

If you’re just about to dive into the BigCommerce platform and want some ideas for where to start, check out the first two articles in this series: Thinking in SaaS and The Main Pillars.

This time around, we’re going to dive a bit deeper into the true backbone of the “open SaaS” platform, and a toolset with which you’ll become well familiar in your developer journey: The BigCommerce APIs. Let’s break the various API systems down in a few different ways.

API Styles

The broadest categories into which BigCommerce APIs fall are according to the API request architecture or “protocol”.

• GraphQL is typically heavily focused on performant data fetching on the client side, and that’s reflected in available BC APIs, which focused first on wide coverage for storefront-related data and contextualizing that data for an individual user. However, GQL coverage continues to rapidly expand. As of now, the full front-end shopping experience from catalog to checkout can be handled with GraphQL queries and mutations.
• REST currently has the broadest coverage, with endpoints for everything from front-end operations like customer registration and cart updates to order management to product creation to theme and widget settings.

A couple API endpoints, namely the Current Customer API and Customer Login API, fall outside these two categories.

Areas

So what can be done with the various BigCommerce APIs? Since “basically everything” is a bit of a glib answer, let’s break things down into some helpful categories.

Storefront Interactions

The primary purpose of the storefront operations in this category is to support headless storefronts, or else to support separate apps that require a customer’s store context. With the power of these API interactions, a fully functional customer experience can be achieved with a front-end that is decoupled from BigCommerce.

Store content includes things like catalog details and page content. Extensive GraphQL coverage in this area makes fetching data specific to the customer’s context easy. The various GET endpoints available in the REST management APIs (see below) can be used to fetch the same details.

Customer login and registration is a key component and involves a few different endpoints/options depending on your needs. 

• The REST Storefront API must be used for initial customer creation.
• GraphQL can be used to log in an existing customer.
• Alternatively, the Customer Login API can be used for single sign-on from a separate web app.
• The Current Customer API allows the secure verification of a customer’s identity by a separate web app.

Cart and checkout data can be accessed and managed both with the REST Storefront API and the GraphQL API.

Data Management

For everything under this heading, REST is the API method in question. Here, we’re talking not about client-side requests, but typical server-to-server CRUD operations to manage your BigCommerce store’s configuration and content. These APIs are the connective tissue that allows your custom apps to extend BigCommerce in myriad ways.

• The Catalog API manages products, categories and brands.
• The Theme and Content API manages entities like your store’s web pages, Page Builder widgets, applied and uploaded themes, and email templates.
• The Webhooks API manages the registration of webhooks allowing external applications to respond to BigCommerce events.
• The Management API encompasses everything else! Collections of endpoints are available for managing customers, orders, channels, pricing, shipping methods, tax rates and more.

The Odd Ones Out

Not fitting entirely in our other categories are:

• The REST Payments API, which is used for initiating BigCommerce’s secure processing of customer payments.
• The GraphQL Account API, which can be used for fetching details and managing users at your account level (as distinct from the store level).

Provider APIs

A final set of APIs worth mentioning is one in which the direction of data is flipped:  For these APIs, it is BigCommerce issuing requests to your own custom application, rather than the other way around. As such, we’re really talking about prescribed schemas rather than APIs BC actually implements.

Your BigCommerce Single-Click App can be registered to provide shipping and tax rates for BC stores that install it, in which case the app must implement the Shipping Provider API or Tax Provider API in order for BigCommerce to fetch rate data.

Endpoints

Another way we can slice the various BigCommerce APIs is according to the endpoints they use. The important distinguishing factor in this respect is the fact that a customer’s session is relevant for some operations. 

The REST Storefront API, GraphQL Storefront API, Customer Login API and Current Customer API are all accessed using paths on your BigCommerce store’s own domain, which facilitates the reading and setting of the user’s session cookie associated with the store.

All other BigCommerce APIs are accessed on a common domain, at api.bigcommerce.com with an identifying store or account ID as a URL segment.

Authentication Methods

Just as the context and purpose of a particular operation affects the endpoint and protocol used for it, the same is true for the appropriate authentication strategy. BigCommerce uses several different techniques for different contexts.

Same Origin Authentication

The REST Storefront API is accessed on your store’s domain and relies on the user’s session context for cart and checkout operations. No authentication is required for these requests, but they must come from the same origin as the domain in the request URI (i.e., your storefront).

Long-Lived Tokens

Most REST operations and the GraphQL Account API rely on authentication via a long-lived token generated in one of the following ways:

• The store owner creates a Store API account in the BC admin. The token can be directly added to the configuration of dedicated apps.
• The store owner installs and authorizes a BigCommerce Single-Click App, initializing an OAuth workflow that grants a token to the application’s App API account. 
• For the GraphQL Account API only, the owner creates an Account API account from their account control panel.

These OAuth tokens are granted specific scopes allowing only the operations that are necessary for their purpose. And having no expiration, they are meant only for API requests from a secure environment where the token will not be exposed to an end user.

Short-Lived Tokens

In some cases, your application must use an endpoint with a typical OAuth token to request a separate, short-lived token. 

This is the primary mechanism for the GraphQL Storefront API, which can make use of:

• A pre-generated token available in the context of your Stencil front-end.
• A standard token generated by the appropriate REST endpoint.
• A customer impersonation token generated by the appropriate REST endpoint.

The first two cases allow for secure requests from a user’s browser, where an authenticated request combined with the user’s session cookie will result in appropriate product listings, pricing, etc., that is specific to the customer context. (Essentially the same use case as the REST Storefront API, but simply a different authentication strategy.)

By contrast, a customer impersonation token is designed for imposing a specific customer context on the response data without a session, and therefore such tokens are meant for server-to-server requests, not for being exposed in a user’s browser!

The Payments API also relies on a one-time-use payment access token generated with a secure REST request.

Signed JWTs

In a couple instances, the challenge of a client-side request is combined with either the need for handling sensitive data or the need for mutual authentication. In these cases, the JSON web tokens (JWT) involved use encrypted/signed payloads that must be decrypted to complete the operation.

Single sign-on with the Customer Login API requires BigCommerce to verify that the user’s request originates with an app that has permission to log the customer in. The app uses its “client secret” to encrypt the customer’s details into a JWT that is then sent with the client-side request. 

The Current Customer API is similar, but the need for authentication is flipped. The app trying to verify a BC customer is who they say they are must verify that the response came from BigCommerce. So in this case, it is BigCommerce that encrypts the customer details - again, using the app’s “client secret”.

In both of these situations, the app must be registered in the BigCommerce Developer Portal in order to generate the client secret used for signing and verification. And in both cases, decrypting the payload using the same secret verifies the identity of the sender.

Conclusion

This has been quite the whirlwind ride! We’ve hardly covered BigCommerce’s APIs in sufficient depth to be ready to sit down and start writing requests from scratch. And yet, if you’re anything like me, the sheer amount of documentation to dive into for these systems can actually be an impediment when you’re trying to wrap your head around the broad concepts. We’ve broken the APIs down in several different ways, exploring those distinctions from the standpoint of the scenarios they serve and why that context creates the need for different strategies. That’s extraordinarily helpful for me as I try to keep complex systems straight, and I hope it has been for you as well!

Read More

• API Documentation
• API Reference
• Authentication Explained
• Stable Token Account Types