Access API¶

The Access API allows authorized third-parties to give and revoke access for certain books to users. This API requires pre-authorization to use certain titles. Please contact help@redshelf.com with any questions.

The Access API only contains two main endpoints: Allow and Revoke. The Allow access gives users perpetual access to an eBook. The Revoke Endpoint removes that access. The third endpoint is the Sample Report Generation endpoint for sample usage data. This endpoint has a separate API scope than the other Access endpoints.

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"
 }

Sample Report Generation¶

/v1/access/sample_usage/

Methods: POST

Retrieve sample usage data for your organization within a specified time window. The maximum window of days permitted is 180 and the suggested usage is 30-180 days. The scope required for the api user is ‘access_sample_report’. Currently the endpoint only works for purchases accessed on or after 2017-09-07. The publisher rep field will only be filled in if the publisher rep email was provided when access to the sample was given out. The ‘samples’ field contains a key for each sample id and these ID’s are not in any order.

Example input:

200 OK
{
 "request": {
  "start_date": "2017-09-08",
  "end_date": "2017-10-15"
 }
}

Example output:

200 OK
{
  "code": 200,
  "success": True,
  "test_mode": False,
  "samples": {
    {
    '1': {
        'Sample Date': '2017-09-30',
        'ISBN13': '1234567890122',
        'EISBN13': '1234567890123',
        'Author': 'Author name',
        'Title': 'Book Title',
        'Edition': 'Book Edition',
        'User First Name': 'First name of sample user',
        'User Last Name': 'Last name of sample user',
        'User email': 'Email of sample user',
        'User Institution': 'Title of the Organization',
        'Date of first viewing at the user level': '2017-08-24',
        'Sample expiration date': 'Date sample will become inactive',
        'Sample status': 'Status: Active or Inactive'
    },
    '4': {
        'Sample Date': '2017-09-30',
        'ISBN13': '1234567890122',
        'EISBN13': '1234567890123',
        'Author': 'Author name',
        'Title': 'Book Title',
        'Edition': 'Book Edition',
        'User First Name': 'First name of sample user',
        'User Last Name': 'Last name of sample user',
        'User email': 'Email of sample user',
        'User Institution': 'Title of the Organization',
        'Date of first viewing at the user level': '2017-08-24',
        'Sample expiration date': 'Date sample will become inactive',
        'Sample status': 'Status: Active or Inactive'
    },
    ...
    }
}

200 OK
{
  "code": 200,
  "success": True,
  "test_mode": False,
  "message": "No samples were created in the specified timeframe: 2017-09-08 - 2017-10-15"
}

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

400 Bad Request: Date
{
  "code": 400,
  "success": False,
  "test_mode": False,
  "message": "The provided dates exceed the date range limit for accessing sample information"
}

400 Bad Request: Organization
{
  "code": 400,
  "success": False,
  "test_mode": False,
  "message": "Your account is not configured properly. Please contact support."
}

Retrieving Viewer Session URL¶

You can retrieve a URL that will allow the user to login by utilizing the Viewer URL Endpoint in the Book API, see Book Viewer