Catalogue API¶

Introduction¶

The Catalogue API allows users to retrieve a files containing books, prices and durations that RedShelf offers. There are two possible catalogue files: RedShelf’s full catalogue or a delta file containing only books with prices that changed from a provided start date. The format of the catalogue files is described below.

Full Catalogue Endpoint¶

The Full Catalogue Endpoint allows API partners to retrieve a URL to download a file containing every book with all of its ownership durations. The provided date allows the API Partner to pick a previous day’s fully generated catalogue file. The full catalogue file is generated once a day. If the catalogue_url is not working, then the file hasn’t been completely generated for that day and the API Partner should periodically check the url. The generation task is kicked off at 10PM Eastern each day so partners should attempt the download after that time. The indicated date should be formatted as YYYY-MM-DD

/v1/catalogue/

Methods: POST

Example input:

{
 'request':
    {
        "date": "2015-05-02"
    }
}

Example output:

200 OK
{
 'code': 200,
 'catalogue_url': 'http://static.redshelf.com/catalogue_3awnk21d1i24.tsv',
 'success': True,
 'test_mode': False
}

400 Bad Request
{
 'code': 400,
 'message": 'The provided start datetime is improperly formed or missing. Please format as YYYY-MM-DD',
 'success': True,
 'test_mode': False
}

Delta Catalogue File Endpoint¶

The Delta Catalogue File Endpoint allows API Partners to specify a datetime and then retrieve all ownership durations that had a price change since that datetime. The datetime should be formatted as YYYY-MM-DD HH:MM. Duplicated requests will return a valid response with the catalogue URL plus an additional field indicating the request was a duplicate.

The initial request starts a file generation task. The API Partner should periodically attempt to retrieve the file at that URL until the generation task completes.

/v1/catalogue/delta/

Methods: POST

Example input:

{
 'request':
    {
        "start_datetime": "2015-05-02 22:35"
    }
}

Example output:

200 OK
{
 'code': 200,
 'catalogue_url': 'http://static.redshelf.com/catalogue_3awnk21d1i24.tsv',
 'success': True,
 'test_mode': False
}

200 OK Duplicate
{
 'code': 200,
 'catalogue_url': 'http://static.redshelf.com/catalogue_3awnk21d1i24.tsv',
 'success': True,
 'message': 'duplicate',
 'test_mode': False
}

400 Bad Request
{
 'code': 400,
 'message": 'The provided start datetime is improperly formed or missing. Please format as YYYY-MM-DD HH:MM',
 'success': True,
 'test_mode': False
}

Single Book Catalogue Pricing Endpoint¶

The Single Book Catalogue Pricing Endpoint allows API Partners to retrieve catalogue pricing data for a given isbn.

The request and the response are in XML format as documented below.

/v1/catalogue/isbn/

Methods: POST Request Content Type: text/xml Response Content Type: text/xml

Example input:

( Note: the SIGNATURE header should be the signed+base64encoded exact string content inside the Request tag,
        in this case "<ISBN>9870123456789</ISBN>" )
<Request><ISBN>9870123456789</ISBN></Request>

Example output:

200 OK
( Note: pretty printed for readability, actual response does not have this extra spacing )
<?xml version="1.0" ?>
<Response>
    <Pricing>
        <PrintISBN>9870123456789</PrintISBN>
        <Type>Ownership</Type>
        <SKU>32325235235235</SKU>
        <DigitalISBN>9870123456789</DigitalISBN>
        <Author>The Doctor</Author>
        <Title>History of the Daleks</Title>
        <ImprintCode></ImprintCode>
        <PublisherName>Some Org</PublisherName>
        <Edition>1</Edition>
        <Copyright></Copyright>
        <AgencyFlag>TRUE</AgencyFlag>
        <AgencyPrice>1.52</AgencyPrice>
        <AllISBNs>9870123456789, 9870123456789</AllISBNs>
        <PricingID>1001</PricingID>
        <HashID>a1b2c3d4e5f6</HashID>
        <OwnershipDuration>LIFETIME</OwnershipDuration>
        <OwnershipEndDate>LIFETIME</OwnershipEndDate>
        <Price>1.52</Price>
        <Status>MODIFIED</Status>
        <PreviousSKU>32325235235765</PreviousSKU>
        <CreatedDate>2017-03-01</CreatedDate>
        <LastModifiedDate>2017-03-01</LastModifiedDate>
    </Pricing>
    <Pricing>
        <PrintISBN>9870123456789</PrintISBN>
        <Type>Ownership</Type>
        <SKU>32325235235235</SKU>
        <DigitalISBN>9870123456789</DigitalISBN>
        <Author>The Doctor</Author>
        <Title>History of the Daleks</Title>
        <ImprintCode></ImprintCode>
        <PublisherName>Some Org</PublisherName>
        <Edition>1</Edition>
        <Copyright></Copyright>
        <AgencyFlag>TRUE</AgencyFlag>
        <AgencyPrice>1.52</AgencyPrice>
        <AllISBNs>9870123456789, 9870123456789</AllISBNs>
        <PricingID>1001</PricingID>
        <HashID>a1b2c3d4e5f6</HashID>
        <OwnershipDuration>30</OwnershipDuration>
        <OwnershipEndDate></OwnershipEndDate>
        <Price>1.52</Price>
        <Status>MODIFIED</Status>
        <PreviousSKU>32325235235765</PreviousSKU>
        <CreatedDate>2017-03-01</CreatedDate>
        <LastModifiedDate>2017-03-01</LastModifiedDate>
    </Pricing>
</Response>

400 Bad Request
<?xml version="1.0" ?><Response><Error>The provided isbn is improperly formed or missing.</Error></Response>

403 Forbidden
<?xml version="1.0" ?><Response><Error>User is not present or not valid.</Error></Response>

404 Not Found
<?xml version="1.0" ?><Response><Error>Pricing for 1234567890123 not found.</Error></Response>

Catalogue File Format¶

Column Headers

Print ISBN: The book’s print ISBN (Max length 13) We will attempt to lookup ISBN13 then fall back to ISBN10. If we cannot match ISBN10 we will default to empty string.
Type: The ownership duration (Max length 255)
- Values: Subscription | Ownership
SKU: Unique ID for a book/ownership duration/price combination. Used for our Point of Sales API (Max Length 30)
Digital ISBN: The book’s digital ISBN (Max Length 13 for isbn13, 10 for isbn10)
Author: Author of the book (Max length 255)
Title: Title of the book (Max length 255)
Imprint Code: Currently Unused
Publisher Name: Name of the publisher of the book (Max length 255)
Edition: Edition number of the book (Integer)
Copyright: Currently Unused
Agency Flag: Indicates if book is wholesale or agency (Boolean True or False)
- Values: TRUE | FALSE
Agency Price: Price of book being sold as agency (Max length 8)
All ISBNs: Comma-separated list of associated ISBNs to this title (TextField)
Pricing ID: ID for a book/ownership combo. Used in our Web API (Integer)
Hash ID: Unique ID for the product (Max length 255)
Ownership Duration: Number of days the subscription ownership lasts. Never provided with Ownership End Date. (Max length 255)
Ownership End Date: Date when the subscription ownership ends. Never provided with Ownership Duration (Max length 255)
Price: The price of the book (Float)
Status: Indicates book pricing status with one of three possible values: NEW, MODIFIED, or DEACTIVATED. Only present for a Catalogue Delta File. (Max length 255)
Previous SKU: The Previous SKU of a book price if a pricing modification has taken place. Only present for a Catalogue Delta File and if the row’s Status is MODIFIED. (Integer)

The first row of the catalogue file is always the column headers. Each column is separated by a tab(‘t’). Each row is separated by a line-feed(‘n’)