4) Bookshelf workflow - Assign Content

Let us imagine a user who has complete the search pictured below. As an e-commerce vendor, you will first process the financial transaction, then you will wish to fetch the content from VitalSource and place it in the user's account. We call this assigning content, and this section of the guide will take you through the various endpoints needed to perform this action.

Catalog Results


It is presumed that before you attempt to perform the next steps you will first possess complete and verified user credentials. If you need guidance on this, you can go to the verify credentials section of the bookshelf workflow. 

Now the rewarding part begins as we combine multiple elements of our service into content assignment endpoints. These steps are as follows:

  1. Get a license
  2. Create a redeemable code for the content
  3. Redeem the code and assign the content to user

1. Get License

The GET v3/licenses - Read endpoint has two valid use-cases.

  1. Get a listing of all content in a users' Bookshelf account
  2. Determine if a specific title currently exists in a users' Bookshelf account

In this workflow we need to use the second use-case and determine if a specific title already is already in a users' account. As we are in process of adding content to user accounts, duplication and race conditions are important to avoid. GET v3/licenses - Read as workflow step can prevent selling a title to user who already owns the content.

We wish to get to the end of a logic test that clears us to create a code for the user. 

When the user clicks on a product you will use their credentials to attempt to GET v3/licenses - Read to ensure the user does not already have this product.

  • To successfully work with this endpoint you will need: 

Below is curl statement that can be pasted into a command line:

curl --location --request GET 'https://api.vitalsource.com/v3/licenses.xml?sku=L-999-70031&license_type=all' \
--header "X-VitalSource-API-Key: YOUR_VST_API_KEY_GOES_HERE"
--header "X-VitalSource-Access-Token: YOUR_VST_TOKEN_GOES_HERE"
--header 'Content-Type: text/xml'

Successful response will include:

  • All licenses associated with this users' access token
  • Details of the SKU
    • Success == <licenses></licensesThis means that no versions of this SKU, in any form are currently licensed to that user and you are free to grant a new license.
    • Note: VitalSource supports duplicate licenses, ad-finitum. If you grant more than one license to a title we simply store the expiration date and remember that. Only one copy of the title ever will appear in the users account. Selling/billing more than one copy of a title is the responsibility of the integrator.
<?xml version="1.0" encoding="UTF-8"?>

2. Create a Code

Using the v3/codes - Create endpoint, you will generate a unique code that can either be given to users or you can redeem it on their behalf as part of a workflow. It should be stressed that creating codes is possibly a billable event, depending on your agreement with VitalSource.

Codes combine multiple properties in the body of the request and our servers place these elements in the license file of the content upon redemption of the code.

The required fields in the body of the request are:

  • sku
  • license-type
    • If you chose absdate, then you will need day/month/year of expiration
    • If your chose numdays, then you will need the number of days until expiration
  • num-codes

To succeed with this endpoint you will need:

  • A valid API key

Below is a curl statement to work with this endpoint

curl -X GET \https://api.vitalsource.com/v3/licenses.xml \
-H "X-VitalSource-Access-Token: YOUR_VST_TOKEN_GOES_HERE"

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<codes sku="BOOKSHELF-TUTORIAL" license-type="default" tag="Test" num-codes="1"/>

Successful response will include:

      • The requested code(s)
<?xml version="1.0" encoding="UTF-8"?>

Users with full accounts will be accustomed to redeeming codes themselves within the application or online product. Codes can also be disseminated to users as you see fit in an institutional setting, but wherever possible we encourage you to redeem the code on behalf of users to streamline the experience and minimize errors.

3. Redeem the Code

Having created a new code(s) you can redeem it using the v3/redemptions - redeem code endpoint and place the content, via a license, in the users VitalSource account  You will need:

  • A valid API key
  • User access token
  • Code that you just created for this user

Below is a curl statement to work with this endpoint

curl -X GET \https://api.vitalsource.com/v3/redemptions.xml \
-H "X-VitalSource-Access-Token: YOUR_VST_TOKEN_GOES_HERE"

<?xml version="1.0" encoding="UTF-8"?>

Successful response will include:

  • The SKU details
<?xml version="1.0" encoding="UTF-8"?>
      <item href="vbk:BOOKSHELF-TUTORIAL" author="VSM" title="Bookshelf Tutorial Updated">

The endpoint will respond with all redeemed items within a library tag, marked as items. This structure is designed around the fact that the v3/redemptions - redeem code endpoint accepts both single and bulk transactions. From an efficiency perspective we recommend collecting codes and grouping them into bulk requests per user whenever possible.  

This completes the workflow of assigning content and the next step in an e-commerce workflow is to Redirect SSO

Was this article helpful?
0 out of 0 found this helpful



Article is closed for comments.