RedShelf Internal eBook API¶

The following information describes how API partners can utilize the RedShelf Internal eBook API to complete API requests. The API was designed to support external partners that would like to license RedShelf’s eReader for their digital content.

The Allow Access endpoint will give users access to viewing content on the licensed eReader on the external partner’s website. The Revoke Access endpoint is for removing user access to viewing content on the licensed eReader on the external partner’s site.

Authentication¶

Authentication is accomplished through a token that is created by RedShelf and given to the external partner.

Request Format¶

Requests for these APIs can be sent as a POST or GET. The details for each URI are documented below.

API Errors¶

In the event of an error occurring while processing your request, the RedShelf API will return an HTTP response code and a description of the error. The following are the possible returned HTTP response codes: 503: Indicates a general server issue 403: Indicates that you lack the authorization for the request we received 400: Indicates you sent an incorrect or malformed response

In addition to the HTTP response code, we will also provide an XML body that contains a description of the errors encountered.

<error>
    The following errors were detected:
  <message>{{Detailed Error Message}}</message>
</error>

The Detailed Error Message possibilities are described with the API endpoints.

User Endpoints¶

/v1/user/

Methods: POST

Create a new user account silently. Password field can be omitted to generate a random password.

Payload:

{
 'email': 'email@address.com',
 'first_name': 'Name',
 'last_name': 'Last',
 'passwd': 'ABC123',
 'passwd_confirm': 'ABC123'
}

POST /v1/user/:

{
 'request':
    {
        'email': 'email@address.com',
        'first_name': 'Name',
        'last_name': 'Last'
    }
}

200 OK:

{
 'code': 200,
 'email': 'example@user.com',
 'passwd': u'Y9ivTu%6uH',
 'message': 'User created.',
 'success': True,
 'test_mode': False,
 'username': '0d72df20f23558620646fb3ea030f5'
}

If the user already exists. you will receive the following response containing the existing user’s username hash.

200 OK:

{
 'code': 200,
 'message': 'User with email address already exists',
 'value': example@user.com,
 'conflict': True,
 'field': 'email',
 'username': '0d72df20f23558620646fb3ea030f5'
}

Allow Access¶

/v1/access/allow/

Methods: POST

Give access to the user for a specific book. The inputs are the hash ID of the book, the user’s username, and the external price that the API partner is using. Expiration date is an optional field which will cause the access to expire on the date provided. Email is an optional field which can be used to track who is sending out access. Send_email is an optional field that, if set to true, will send the user an email notifying them that they have been given access to the book.

Example input:

{
 "request": {
  "hash_id": "ccc5a093f5ee30ec749e4909840f0f7b794066bb",
  "username": "0d72df20f23558620646fb3ea030f5",
  "price": "21.46",
  "expiration_date": "2015-12-31 00:00:00",
  "email": "email@domain.com",
  "send_email": False
 }
}

Example output:

200 OK
{
 'code': 200,
 'success': True,
 'test_mode': False
}

404 Not Found: Book
{
 "code": 404,
 "error": True,
 "test_mode": False,
 "message": "Book not found"
 }

404 Not Found: User
{
 "code": 404,
 "error": True,
 "test_mode": False,
 "message": "User not found"
 }

401 Unauthorized: Book
{
 "code": 401,
 "error": True,
 "test_mode": False,
 "message": "Not Authorized for Book"
 }

400 Bad Request: Purchase
{
 "code": 400,
 "error": True,
 "test_mode": False,
 "message": "The user already has access to this book"
 }

400 Bad Request: Price
{
 "code": 400,
 "error": True,
 "test_mode": False,
 "message": "The price field was supplied an invalid value"
 }

400 Bad Request: Email
{
 "code": 400,
 "error": True,
 "test_mode": False,
 "message": "The email field provided was invalid"
}

Revoke Access¶

/v1/access/revoke/

Methods: POST

Revoke access for a user to a specific book. If the user doesn’t have access, then a 404 is returned.

Example input:

200 OK
{
 "request": {
  "hash_id": "ccc5a093f5ee30ec749e4909840f0f7b794066bb",
  "username": "0d72df20f23558620646fb3ea030f5"
 }
}

Example output:

200 OK
{
  "code": 200,
  "success": True,
  "test_mode": False
}

404 Not Found: Book
{
 "code": 404,
 "error": True,
 "test_mode": False,
 "message": "Book not found"
 }

 404 Not Found: User
{
 "code": 404,
 "error": True,
 "test_mode": False,
 "message": "User not found"
}

401 Unauthorized: User
{
 "code": 401,
 "error": True,
 "test_mode": False,
 "message": "Not Authorized for Book"
 }

404 Not Found: Purchase
{
 "code": 404,
 "error": True,
 "test_mode": False,
 "message": "Purchase record not found"
 }

Book Endpoints¶

/v1/book/index/

Methods: GET

Obtain a list of books controlled by the current account.

GET /v1/book/index/

200 OK:

{
 'code': 200,
 'count': 1,
 'results': [
    '<book object>'
 ],
 'success': True,
 'test_mode': False
}