1) Bookshelf workflow - v4/products

Our newly updated v4/products - Read All endpoint is is designed for content ingestion by our API integrators . For many e-commerce sites, this is the first step for their integration with VitalSource. At VitalSource, you can find more than a million titles.

We will discuss two use cases of the product endpoint:

  • New: Construct a catalog for the first time by consuming the entire VitalSource product list
  • Deltas: Update your site with a (period) specific GET


Catalogs can quickly be built at the v4/products - Read All endpoint. To work with this service you will need:

  • A valid API key
    • As parameters to the header you can limit the response by:
    • Date, pages or currency
  • JSON is the default data structure: Here is an example curl statement. Paste this code into a terminal window and you will GET product data from VitalSource.
curl -X GET \ https://api.vitalsource.com/v4/products" \
-H "X-VitalSource-Access-Token: YOUR_VST_TOKEN_GOES_HERE"
-H 'Content-Type: application/json' \

A successful response will look like this:

    • Item and page counts
    • Individual items as requested
"num_items": 198974,
"page": 1,
"per_page": 1000,
"total_pages": 199,
"items": [
       "vbid": "0-02-013050-3",
       "identifiers": {
       "print_isbn_canonical": null,
       "eisbn_canonical": null


curl -X GET \ https://api.vitalsource.com/v4/products?=page2" \
-H "X-VitalSource-Access-Token: YOUR_VST_TOKEN_GOES_HERE"
-H 'Content-Type: application/json' \

As you can see from this example response we have received the first of 200 pages with the endpoint defaulting to 1,000 items per page. Now you would iterate through the pages by modifying your request to:

Once you have consumed the entire catalog, in this manner (approx. two hours as JSON), you will be up to date. You should expect more than a million records. Now you can switch over to maintenance mode, where you will need to keep in sync with our catalog by updating deltas. 


To GET deltas for an existing catalog, you will also use the product endpoint with revised parameters. In the example below, we will seek all catalog updates since the beginning of 2017. 

curl -X GET \https://api.vitalsource.com/v4/products?from=2017-01-01T00:00:00Z" \
-H "X-VitalSource-Access-Token: YOUR_VST_TOKEN_GOES_HERE"
-H 'Content-Type: application/json' \


"num_items": 368327,
"page": 1,
"per_page": 1000,
"total_pages": 369,

The response will be identical to that you received above in structure; but with a smaller dataset:

    • To reduce payload, the service does not by default include all metadata in requests. These elements are available as params and can be specified as in:
      • https://api.vitalsource.com/v4/products?include_details=subjects
      • https://api.vitalsource.com/v4/products?include_details=metadata

 You can use the same logic (from initial load of the catalog) to iterate through the pages until you have completed consumption of the update.

With these steps complete, you can now work on Bookshelf workflow - v3/users.

Was this article helpful?
2 out of 3 found this helpful



Article is closed for comments.