CoursesCatalog - REST APIModule 3: Working with Products

Working with Products

Plan: Developer Foundations

 Lesson 5 of 21 · 30 min

Whether you are creating new products, updating existing products, or just reading product information, being able to include or exclude information will help in drilling down to the specific data you need and reducing the amount of requests needed to complete tasks.

The fill-in-the blank exercises in this course are simulated for demonstration and learning purposes only. You will run real API requests in the Hands-on Labs as you progress through the course.

GET All Products

To return a list of Products in a store, send a GET request to /catalog/products.

Example:

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products

GET Products Channel Assignments

To return a list of products channel assignments in a store, send a GET request to /catalog/products/channel-assignments

Example:

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/channel-assignments

Filters

Filters give you the ability to specify what’s included in the response, whether that’s including extra properties that are not normally returned, or just reducing how many things are returned. That overhead will add up as your application scales. If you are managing inventory for multiple stores and you want to be able to scale, it makes sense to control the data you get back from BigCommerce per request.

Instead of getting the entire product object, you might want to retrieve just one property. That way the actual size of the response is much smaller so your overhead is reduced.

While the overhead in your application is reduced, due to the way REST is architected, the load on BigCommerce’s side is not. All fields are fetched, and then the unwanted fields are not sent in the response. If your application requires real time display of product information (like a headless storefront) consider using GraphQL, which avoids this.

Include

Include allows you to request more information than what comes back in a typical response. However, because you are increasing the size of your request, it may slow down your response.

As an example, you can include a product’s variants and images with the product response:

/v3/catalog/products?include=variants,images

Certain endpoints support the include query parameter used to include sub-resources and specific attributes in the primary GET response for a parent object. For more information about whether an endpoint supports the include parameter, consult the API reference for the endpoint in question.

Refer to the GET method for any specific endpoint to see a list of fields that can be included.

Including and Excluding Fields

include_fields will return the specified fields in the response.

exclude_fields will omit the specified fields from the response.

You can specify any field that is available on the object. Excluding fields you don’t care about (especially large fields like descriptions) can speed up your API request response time.

Example:

GET /v3/catalog/products?include_fields=name,price

Example response

Pagination and Limit

  • ?page will determine which page of the request you are viewing
  • ?limit will determine the number of results per page that are returned
  • ?page=2&limit=10 will return page 2 of the results with 10 items per page

Example:

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products?page=2&limit=10

This will return page 2 of the results with 10 items per page.

If you scroll down to the bottom of the response, you will see a section called “meta.” This is metadata that is included with every Catalog API request.

Metadata

For our discussion, we’ll define metadata as additional information that is included on every Catalog (V3) API request.

Metadata is really helpful; previously in V2 you would have to make several API requests, to understand things like the total number of records and pages. Not anymore! The metadata displays parameters for the previous, current, and next pages, how many total pages there are, and which page you are currently on. With one request you can figure out all the information.

Metadata example:

"meta": {
  "pagination": {
    "total": 25,
    "count": 5,
    "per_page": 5,
    "current_page": 1,
    "total_pages": 5,
    "links": {
      "next": "?limit=5&page=2",
      "current": "?limit=5&page=1"
    },
    "too_many": false
  }
}

Resources