Sony DADC User Rights Management Solution

Common Gateway Platform Application Programming Interface (API)

Purpose

This document covers Common Gateway Platform Back-Office API (Contents management) interface specification for Store.

Generic Parameters

Assumptions and Conventions

The protocols used in this system are HTTP/1.1 and SSL(HTTPS). Content Type for POST Request:
application/x-www-form-urlencoded

Each API has certain version information: the current version is v.2.0. The response format is:
Content-Type: application/json; Charset=utf-8

Authentication

Every request needs to be authenticated. Authentication is done by checking an authentication string which needs to be passed with every request.

The string is made up of the store ID, the current Unix timestamp and an authentication hash.

The authentication hash is created by using a SHA256-HMAC. The key for the HMAC calculation is the store secret and the message is the concatenation of the path of the current request and the current Unix timestamp.

The path includes the leading slash and excludes the query string. The result of this HMAC is base 64 encoded.

Base 64 encoded strings may hold symbols that cannot be directly used as URL parameters. Encode them as URL first. This also applies to all POST parameters, as application/x-www-form-urlencoded parameters are likely to appear in POST content.

On server side the authentication is done by validating the authHash and also by checking if the timestamp is within a certain period of time (5 minutes).

HMAC message: [request path][timestamp]
authHash: base64(sha256-hmac(HMAC message)
authentication String: [storeID]-[timestamp]-[authHash]
url encoded authentication String: urlEncode(authentication String)

Examples:

request: http://localhost:8080/cgp.bo/v2/content/packaging/open/session
HMAC message:  /cgp.bo/v2/content/packaging/open/session/1441001719
authHash: /dk/MprCAy7WYz5ON3alTSOQ8IFcx6xxspW2cnw++RYw=
authentication String: 100-1441001719-dk/MprCAy7WYz5ON3alTSOQ8IFcx6xxspW2cnw++RYw=
url encoded authentication String: 100-1441001719-dk%2FMprCAy7WYz5ON3alTSOQ8IFcx6xxspW2cnw%2B%2BRYw%3D

Resource URL

Name URL based on the following format. Variable value should be expressed using “${” and “}”.
HTTP Method /bo/v${Version #}/${Processing Object(name)}/:${Processing Object’s ID(Optional)}

Name API that does not refer to, register, update or delete resources based on the following format.
HTTP Method /bo/v${Version #}/${Processing Object(name)}/${Processing Object’s ID(Optional)}/${Action Verb}

Parameters

authString: signature for authentication

URI Resource Value

ccid: Common Content ID of the content to be updated.

Response

status: See Response Status.
message: Messages for developers (Response status)

Content API

Open Packaging Session

Open Packaging Session is an API to start encryption processing.

This API returns a Session ID, and temporary ID codes for requested files.

Resource Path

POST /bo/v2/content/packaging/open/session/

Parameters Required

count: Number of files to upload

Response

packagingSessionId: Issued SessionId for packaging (encryption) process
temporaryId: A temporary ID code for uploaded contents

Sample Response

{
        "status": 0,
        "message": "Success.",
        "packagingSessionId": "TJ45NCCAPVGAJES5GFYYATLT4K4KDA5L",
        "books": [
                { "temporaryId": "USQD4EHLVHXM6YWG7S6AURAJFGYY46XA" },
                { "temporaryId": "SNXHQJWLP4JRAQ7QT35JAYGEXEHM379Q" }
        ]
}

Upload Package File

Upload Package File is an API for uploading book content to be encrypted.
Metadata also needs to be uploaded.

Resource Path

POST /bo/v2/content/packaging/upload/

Required Parameters

packagingSessionId: This matches the packagingSessionId issued at Open Packaging Session API.
temporaryId: This matches the temporaryId issued by the Open Packaging Session API.
data: EPUB2, EPUB3, or PDF format file, base64-encoded
If using division upload, divide the target file into fragments, and encode each fragment as base64.
Call this API multiple times.
format: 0: PDF
1: EPUB2
2: EPUB3
title: Book title
externalId: Content ID used in external systems (Book Store System) such as ISBN
hash: This is MD5 hash information of the original book file (before the book file has been split into parts)
numberOfSplitFiles: Number of parts that the book was split into (must be greater than or equal to 1)
index: Index of the currently uploaded chunk (starting at 1)
publisherName: Name of the Publisher

Optional Parameters

contentUrl:The URL to the location of the encrypted content file.

ccid: Target CCID is required when content will be regenerated
updateRevision: 0: Version is not incremented
1: Version is incremented
ageLimit: Age restriction
thumbnailUrl: Thumbnail URL
storeName: The name of the store. When not specified, a default store name that is already registered will be used.
copyDuration: Time left for copying content. Specifying the number of seconds is recommended.
It is recommended to start counting after the content has been downloaded.
copyUntil: Date and time of expiration for copying. UTC is recommended. For example, “2016100113” means “valid until 1 pm, 10/01/2016”
When both “copyDuration” and “copyUntil” are specified, we recommend that whichever date comes first be used to define the method to use.
copyCount: Number of copies
printDuration: Time left for printing content
printUntil: Date and time of expiration for printing. UTC is recommended. For example, “2016100113” means “valid until 1 pm, 10/01/2016”
printResolution: Maximum resolution allowed for printing (DPI is recommended)
printCount: Number of print copies
allowWebReading: 0: this book will not be readable online (default)
1: this book will be available for online reading
exclusionList: Contains a JSON array of EPUB Resource Files that must not be encrypted.

Example:

The EPUB file contains a folder OEBPS/chapters which holds all the chapters, and OEBPS/images which contains pictures.
If the first chapter and the cover picture should be excluded from encryption the exclusion list would look like this:

[“OEBPS/chapters/chap1.xhtml”, “OEBPS/images/cover.png”]

Sample Response

{
        "status":0,
        "message":"Success."
}

Get Packaging Status

This is an API for status check of encryption processing
The API returns processing status with requested Session ID.

Resource Path

POST /bo/v2/content/packaging/get/status/

Required Parameters

packagingSessionId: This matches the packagingSessionId issued by the Open Packaging Session API.

Response

books: temporaryId Target temporaryId to be confirmed
packagingStatus: 0: Waiting
1: Processing
2: Completed normally
3: Completed with warning
4: Closed
9: Abnormal end
statusDescription: Status description
ccid: This is issued content ID after process completion
externalId Content ID used in external systems (Book Store System), such as ISBN
version: Content version. The number returned at the initial registration is always “1.”
downloadUrl: This is the URL to use to download content after the process is complete.
Sample Response

{
        "status": 0,
        "message": "Success.",
        "books": [
                {
                "temporaryID": "P38M7YWETV5DQRUGCES79E6RWUDTVUVB"
                "packagingStatus": 2,
                "ccid": "XBCQVWKE6WSQ8Q9XB7DEEX9H73DGW3FN",
                "downloadUrl": "http://54.250.127.21/contents/XBCQVWKE6WSQ8Q9XB7DEEX9H73DGW3FN/0/4snnzajqkq.MNB",
                "version": 1,
                "externalId": "282",
                "statusDescription": "None",
                }
        ]
}

Close Packaging Session

This API closes the encryption process. It is used to delete any unnecessary files or queue.

Resource URL

POST /bo/v2/content/packaging/close/session/

Parameters Required

packagingSessionId: This matches the packagingSessionId returned by the Open Packaging Session API.

Sample Response

{
        "status":0,
        "message":"Success."
}

CGP Back Office API V3

Purpose

This document covers Common Gateway Platform Back-Office API (Content management) interface specification. You will get detailed technical information on the webservice calls including input parameters and return values.

If you are interested in a more general overview of the content management workflow you might want to look at CGP Back Office.

Generic Parameters

Assumptions and Conventions

The protocols used in this system are HTTP/1.1 and SSL (HTTPS).

Content Type for POST Request:
application/x-www-form-urlencoded
Each API has certain version information: the current version is v.3.0.

The response format is Content-Type:
application/json; Charset=utf-8

Data in requests is accepted as attached JSON format files.

Authentication

Every request needs to be authenticated. Authentication is done by checking an authentication string which needs to be passed with every request.

The string is made up of the store ID code, the current Unix timestamp and an authentication hash.

The authentication hash is created by using a SHA256-HMAC. The key for the HMAC calculation is the store secret and the message is the concatenation of the path of the current request and the current Unix timestamp.

The path includes the leading slash and excludes the query string. The result of this HMAC is base 64 encoded.

Base 64 encoded strings may hold symbols that cannot be directly used as URL parameters. Encode them as URL first. This also applies to all POST parameters, as application/x-www-form-urlencoded parameters are likely to appear in POST content.

On server side the authentication is done by validating the authHash and also by checking if the timestamp is within a certain period of time (5 minutes).

HMAC message: [request path][timestamp]
authHash: base64(sha256-hmac(HMAC message)
authentication String: [storeID]-[timestamp]-[authHash]
url encoded authentication String: urlEncode(authentication String)

Examples:

request: <http://localhost:8080/cgp.bo/v3/content/packaging/open
HMAC message: /cgp.bo/v3/content/packaging/open1441001719
authHash: dk/MprCAy7WYz5ON3alTSOQ8IFcx6xxspW2cnw++RYw=
authentication String: 100-1441001719-dk/MprCAy7WYz5ON3alTSOQ8IFcx6xxspW2cnw++RYw=
url encoded authentication String: 100-1441001719-dk%2FMprCAy7WYz5ON3alTSOQ8IFcx6xxspW2cnw%2B%2BRYw%3D

Response

Every response contains at least two values which give you information on success or failure of the call.

status: A status code which is 0 for success or any other number for a failure. See Response Status for more information on the different values.
message: A message describing the status in a more human readable form.

Back Office API V3

Open Packaging Session

This call initializes a packaging session. You need to open a packaging session per product you want to protect.

It contains all required metadata of the product as well as the DRM restrictions.

It returns the packaging session ID code, used throughout the process to identify the session.

Resource Path

POST /bo/v3/content/packaging/open

Required Parameters

title: The title of the book
externalId: This should be an identifier you use in your system to identify the book.

This could be, for example the ISBN or any proprietary ID value. This ID code will also be included in callbacks and other responses.

So it will also help you link our messages to your products.

format: ID for the book format, 0 for PDF, 1 for EPUB2, 2 for EPUB3
publisherName: Publisher of the book
hash: The md5 hash of the book you are going to upload in this session
numberOfFileFragments: It is possible to split very large files into several fragments for uploading. This is the number of fragments. If you are going to upload the book as a whole, set this to 1.

Optional Parameters

contentUrl: The URL where you are going to host the encrypted content. If the content URL is set, the reader app will be able to download the book automatically. The store does not need to know about the storage location.
thumbnailUrl: The URL where the thumbnail image of the book is hosted. This information can be fetched by the client applications along with other book metadata.
exclusionList: Contains a JSON array of EPUB Resource Files that must not be encrypted. For example, the EPUB file contains a folder OEBPS/chapters that holds all the chapters, and another folder called OEBPS/images that holds pictures.

If the first chapter and the cover picture should be excluded from encryption the exclusion list would look like this:

[“OEBPS/chapters/chap1.xhtml”, “OEBPS/images/cover.png”]
allowWebReading: Should this book be available for reading on the web?
0: This book will not be readable online (default)
1: This book will be available for online reading
ageLimit: minimum age to be allowed to read the book
distributorManaged: If this flag is set to 1, buy and lend operations cannot be completed using the URMS API. These operations must be completed by the distributor’s API.
copyDuration:
copyUntil:
copyCount:
printDuration:
printUntil:
printResolution:
printCount:

Response

packagingSessionId: identifier for this packaging process.

Sample Response

{
    "status": 0,
    "message": "Success",
    "packagingSessionId": "TJ45NCCAPVGAJES5GFYYATLT4K4KDA5L"
}

Upload File

This request is used to upload the actual content for an opened packaging session. The request must be encoded as multipart request.

Resource URL

POST /bo/v3/content/packaging/upload

Required Parameters

packagingSessionId: The identifier for this packaging session. This ID can be obtained by the openPackagingSession call.
fragmentIndex: In case of fragmented upload this index gives the sequence number of the current index.
If the file is uploaded as a whole, set this to one.
hash: The md5 hash of the fragment
file: the binary data of the content

Response

There are no values returned except status and status description.

Sample Response

{
    "status":0,
    "message":"Success"
}

Finish Upload

This request is used to signal the the upload of all files is finished and CGP can start processing to workload.

Resource URL

POST /bo/v3/content/packaging/finish

Required Parameters

packagingSessionId: The identifier for this packaging session. This ID code can be obtained by the openPackagingSession call.

Response

There are no values returned except status and status description.

Sample Response

{
    "status":0,
    "message":"Success"
}

Get Packaging Status

This is an API for status check of encryption processing
The API returns processing status with requested SessionId.

Resource URL

POST /bo/v3/content/packaging/get/status

Required Parameters

packagingSessionId: The identifier for this packaging session. This ID can be obtained by the openPackagingSession call.

Response

packagingStatus: The ID of the packaging status. See Packaging Status description in the Appendix.
statusDescription: Details of the status. Note that the packager that writes information to this field always work with the latest version.
externalId: the external ID you provided in the openPackagingSession call

If the packaging process is finished, either successfully or with warnings there are additional return values.

ccid: This ID is required for any content related operation by the store or the client.
It uniquely identifies the book in the CGP system.
downloadUrl: The URL where the protected book can be downloaded.
hash: The md5 hash of the encrypted file.

Sample Response

{
    "status": 0,
    "message": "Success",
    "packagingStatus": 4,
    "statusDescription": "",
    "externalId": "282",
    "ccid": "XBCQVWKE6WSQ8Q9XB7DEEX9H73DGW3FN",
    "downloadUrl": "http://54.250.127.21/contents/XBCQVWKE6WSQ8Q9XB7DEEX9H73DGW3FN/0/4snnzajqkq.MNB",
    "hash": "692c0b36504c2f2052df9878608a0e56"
}

Close Packaging Session

This call is used to tell CGP that you are are finished with this session, either because you have successfully downloaded the protected file or you want to abort the session for any reason.

When receiving this call CGP will delete all files belonging to this session. This includes the unprotected files and file fragments, the protected file, and any intermediate files which might have been created.

Resource URL

POST /bo/v3/content/packaging/close

Required Parameters

packagingSessionId: The identifier for this packaging session. This ID can be obtained by the openPackagingSession call.

Sample Response

{
    "status":0,
    "message":"Success"
}

Update Metadata

Using this call you can update metadata information or DRM information for a book.
All existing data will be overwritten with the data contained in this call.

Resource URL

POST /bo/v3/content/packaging/update

Required Parameters

ccid: The ID of the book you want to update
title: The title of the book
externalId: This should be an identifier you use in your system to identify the book, such as the ISBN or any proprietary ID.
This ID code will also be included in callbacks and other responses. So it will also help you link our messages to your products.
format: ID for the book format, 0 for PDF, 1 EPUB2, and 2 EPUB3. See the description of the book format in the Appendix.
publisherName: Publisher of the book
contentUrl: The URL where you are going to host the encrypted content.
If the content url is set, the reader app will be able to download the book automatically.
The store does not need to know the storage location.
thumbnailUrl: The URL where the thumbnail image of the book is hosted.
This information can be fetched by the client applications along with other book metadata.
allowWebReading: Should this book be available for reading on the web?
0: This book will not be readable online (default)
1: This book will be available for online reading
distributorManaged: If this flag is set to 1, buy and lend operations cannot be completed using the URMS API. These operations must be completed by the distributor’s API.
ageLimit: minimum age to be allowed to read the book
copyDuration:
copyUntil:
copyCount:
printDuration:
printUntil:
printResolution:
printCount:

Response

version: Every update creates a new version of the book. This is the current version number.

Store API

Purpose

This document aims to specify the interface between the retailer (store) and the Common Gateway Platform (CGP).

If you are interested in a general overview of the workflow and features of the Store See Common Gateway Platform Store.

Assumptions and Conventions

The protocols used in this system are HTTP/1.1 and SSL(HTTPS)

The response format is Content-Type: application/json; Charset=utf-8

Data in requests is accepted as attached JSON format files.

Authentication

Every request needs to be authenticated. Authentication is done by checking an authentication string which needs to be passed with every request.

The string is made up of the store ID, the current Unix timestamp and an authentication hash.

The authentication hash is created by using a SHA256-HMAC. The key for the HMAC calculation is the store secret and the message is the concatenation of the path of the current request and the current unix timestamp.

The path includes the leading slash and excludes the query string. The result of this HMAC is base 64 encoded.

Base 64 encoded strings may hold symbols that cannot be directly used as URL parameters. Encode them as URL first. This also applies to all POST parameters, as application/x-www-form-urlencoded parameters are likely to appear in POST content.

On server side the authentication is done by validating the authHash and also by checking if the timestamp is within a certain period of time (5 minutes).

HMAC message: [request path][timestamp]
authHash: base64(sha256-hmac(HMAC message)
authentication String: [storeID]-[timestamp]-[authHash]
url encoded authentication String: urlEncode(authentication String)

Examples:

request: http://localhost:8080/cgp.store-api/v2/users/jdoe/books/FJYMC6N4YRJ9KMSTN4QNYAXDU9AMD8UL/stores/buy/
HMAC message: /cgp.store-api/v2/users/jdoe/books/FJYMC6N4YRJ9KMSTN4QNYAXDU9AMD8UL/stores/buy/1441002336
authHash: ecmoziv6VcsvjDIsy01mZBLxPxCUjGzbQb46DRvo+h4=
authentication String: 100-1441002336-ecmoziv6VcsvjDIsy01mZBLxPxCUjGzbQb46DRvo+h4=
url encoded authentication String: 100-1441001719-dk%2FMprCAy7WYz5ON3alTSOQ8IFcx6xxspW2cnw%2B%2BRYw%3D

Parameters

authString: signature for authentication

Generic Response Values

The response always contains a status and a message. The status is a number which signals either success (0) or the type of error. For a list of possible status codes see Response Status.

A response which does not contain any additional data will look like this:

{
     "statusCode": 0,
     "message": "Success"
}

There are a few status codes which can be returned for every request. This is because of the possible errors in the authentication procedure which is part of every request. They are listed below.

  • SUCCESS (0)
  • INVALID_PARAMETER (20)
  • AUTHENTICATION_FAILURE (10)
  • OUTDATED_REQUEST (12)
  • INTERNAL_ERROR (99)

User Management API

Register User

To be able to do any operation for a user, the user must first be registered with CGP. The Register User web service operation is used for this purpose; it is only completed one time for each user.

Request

POST /store/v2/users/{userId}

URL Parameters

userID This must be a unique identifier for your store. It will be used to identify the user in subsequent requests.

Errors

INVALID_USER_STATUS: This error can occur if the user name already exists.

Sample Response

{ 
     "statusCode": 0,
     "message": "Success"
}

Delete User

This process deletes a user from the CGP server. Any further requests coming from this user will be denied. When a user account is deleted the process completes the following processes related to that account:

  • Get back any books the user lent to other users
  • Return any books the user borrowed
  • Cancel sale of books
  • If the user is the administrator of a user group, that group will also be deleted.
  • If the user was connected to a common bookshelf, the user’s account will be removed from the bookshelf, as well as any of the books that user owned.

Request

POST /store/v2/users/{userId}/delete

URL Parameters

userID The user ID for the user record you want to delete.

Errors

USER_NOT_FOUND: This error can occur if the specified user does not exist or was already deleted.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Generate AuthToken

The authtoken is used to register a device for a user.

It is required by the reader application and therefore will usually be requested via some interface between the retailer (store) and the reader.

The token can only be used a single time and is only valid for a few minutes.

Request

POST /store/v2/users/{userId}/authtoken/generate

URL Parameters

userID The user ID used to register the user with URMS.

Response

authToken: [authTokenId]:[randomValue]

Errors

USER_NOT_FOUND: The specified user does not exist or was already deleted.

Sample Response

{
         "statusCode": 0,
         "message": "Success.",
         "authToken": "3375:z4nk82tdj32hf4ad"
}

Book Transaction API

Get Lend Expiry

Retrieve the expiry date and some additional information for a users lends.

Request

POST /store/v2/users/{storeUserId}/books/lendExpiries

URL Parameters

userID The user ID for the user you want to find an expiration date for.

Optional POST Data

includeCommonBookshelf: True or false. Selects if the books from the common bookshelf should be included in the result. Default value is false.
ccids: This parameter can occur multiple times. Restricts the results to the CCIDs in this list. If this parameter is not present, then all books which are lent are evaluated, and may be returned.

Response

expiries: Array of books which are being lent together, with the details on the lend transaction.
commonBookshelf: True if the book is available through the common bookshelf, false otherwise
ccid: The unique identifier of the book
expiry: The Unix timestamp of the end of the lending period
transactionType: LEND, BORROW, or STORE_LEND. Showing if the books is borrowed from another user or a store or if the book is lent to another user.

Errors

USER_NOT_FOUND: The specified user does not exist or was already deleted.

Sample Response

{
    "statusCode": 0,
    "message": "Success",
    "expiries": [
        {
            "commonBookshelf": true,
            "ccid": "S9LEST9WBMGW8LWAD8UR6S9464WSJJ3F",
            "expiry": 1454706344,
            "transactionType": "BORROW"
        },
        {
            "commonBookshelf": false,
            "ccid": "S9LEST9WBMGW8LWAD8UR6S9464WSJJ3F",
            "expiry": 1454706894,
            "transactionType": "BORROW"
        },
        {
            "commonBookshelf": false,
            "ccid": "XETBGVU6GN3PGRULTLJYDPPWKYYJRULN",
            "expiry": 1454681422,
            "transactionType": "BORROW"
        }
    ]
}

Buy Book

Registers the rights for a book to a user. This adds the book to the users bookshelf and makes the book available for reading.

Note that it is possible that some books are managed by the content distributor. This means that the buy transaction can not be executed via the URMS Store-API but needs to be invoked by the distributor or content owner. The distributor will take care of registering the transaction at the URMS system.

Request

POST /store/v2/users/{userId}/books/{ccid}/stores/buy

The URL contains the buyer’s user ID code and the CCID code for the book.

Required Parameters

price: Actual price of the book using a period (.) as decimal separator.
currency: ISO code of the currency that is used, such as EUR, USD, or JPY.

Errors

USER_NOT_FOUND: The specified user does not exist.
CONTENT_NOT_FOUND: The specified ccID code cannot be found.
INVALID_CONTENT_STATUS: The specified user already owns the book.
ACCESS_DENIED: Direct access to the content is not allowed. Transactions need to be registered using the content distributor’s API.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Buy Book on Behalf

This operation works just like the buy book operation, but with the difference that one partner can register the buy operation on behalf of another retailer. The main use case is to enable content distributors to manage transactions on their products on their own. Therefore all direct transactions via the URMS API can be blocked by setting the appropriate flag during the product packaging.

To be able to do transactions on behalf of another partner this needs to be allowed in the partner configuration. The operation will work only if your account is listed as an authorized partner for the retailer.

Request

POST /store/v2/users/{userId}/books/{ccid}/stores/buyOnBehalf

The URL contains the buyer’s user ID code and the CCID code of the book.

Required Parameters

retailerid: The ID code for the retail partner
price: Actual price of the book using a period ”.” as decimal separator
currency: ISO code of the currency that is used (e.g. EUR, USD, JPY etc.)

Errors

USER_NOT_FOUND: The specified user does not exist.
CONTENT_NOT_FOUND: The specified ccID code cannot be found.
INVALID_CONTENT_STATUS: The specified user already owns the book.
ACCESS_DENIED: Direct access to the content is not allowed. Transactions need to be registered using the content distributor’s API.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Lend Store Book

Temporarily registers the rights for a book to a user. This adds the book to the user’s bookshelf and makes the book available for reading.

The lending period can be either overwritten or extended. If the lending period is overwritten and the new expiration date is past, the lending period automatically expires. If the lending period is to be extended, but the lending period for the book does not exist or is already expired, a new lending period is created.

Note that it is possible that some books are managed by the content distributor. This means that the lend transaction can not be executed via the URMS Store-API but rather needs to be invoked using the distributor’s API. The distributor will take care of registering the transaction at the URMS system.

Request

POST /store/v2/users/{userId}/books/{ccid}/stores/lend

The URL contains the lender’s user ID code and the CCID code of the book that was borrowed.

Required POST Data

termSec: Lending period in seconds

Optional POST Data

operationType:

1: Overwrite(Default)

2: Append

price: Actual price of the book using a period ”.” as decimal separator
currency: ISO code of the currency that is used, such as EUR, USD, or JPY

Errors

USER_NOT_FOUND: The specified user does not exist.
CONTENT_NOT_FOUND: The specified ccID code cannot be found.
INVALID_CONTENT_STATUS: The specified user already owns the book.
ACCESS_DENIED: Direct access to the content is not allowed. Transactions need to be registered using the content distributor’s API.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Lend Store Book on Behalf

This operation works just like the Lend Store Book operation, but with the difference that one partner can register the lend operation on behalf of another retailer. This allows content distributors to manage product transactions on their own. Therefore all direct transactions via the URMS API can be blocked by setting the appropriate flag during the product packaging.

To be able to do transactions on behalf of another partner this needs to be allowed in the partner configuration. The operation will work only if your account is listed as an authorized partner for the retailer.

Request

POST /store/v2/users/{userId}/books/{ccid}/stores/lendOnBehalf

The URL contains the lender’s user ID code and the CCID of the book that was borrowed.

Required POST Data

retailerId: The ID code for the retail partner
termSec: Lending period in seconds

Optional POST Data

operationType:

1: Overwrite(Default)

2: Append

price: Actual price of the book using a period ”.” as decimal separator
currency: ISO code of the currency that is used, such as EUR, USD, or JPY

Errors

USER_NOT_FOUND: The specified user does not exist.
CONTENT_NOT_FOUND: The specified ccID code cannot be found.
INVALID_CONTENT_STATUS: The specified user already owns the book.
ACCESS_DENIED: Direct access to the content is not allowed. Transactions need to be registered using the content distributor’s API.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Revoke Transaction

Remove the rights to a book for a user. The book will not longer be available for the user to read or complete any other transactions, like lending the title to a friend. This operation only works if the book is in the possession of the user.

Request

POST /store/v2/users/{userId}/books/{ccid}/revoke

The URL contains the owner’s user ID code and the CCID code of the book to be revoked.

Errors

USER_NOT_FOUND: The specified user does not exist or has already been deleted.
CONTENT_NOT_FOUND: The specified ccID has never been owned by the user or does not exist.
INVALID_CONTENT_STATUS: The specified user does not own the book any longer.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Lend Book

Lend a book to another user.

Request

POST /store/v2/users/{userId}/books/{ccid}/lend

The URL contains the lender’s user ID code and the CCID code of the book to be lent.

Required POST Data

borrowerId: Borrower’s CGP User ID
termSec: Lending period (in seconds)

Errors

USER_NOT_FOUND: The specified user does not exist.
CONTENT_NOT_FOUND: The specified ccID code cannot be found.
INVALID_CONTENT_STATUS: The specified user already owns the book or the lender has already lent the book to another borrower.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Get Back Book

The owner can get a specified book back from the borrower before the lending period expires.

Request

POST /store/v2/users/{userId}/books/{ccid}/getback
The URL contains the owners’s userId and the CCID code of the book to be returned.

Errors

USER_NOT_FOUND: The specified user does not exist
CONTENT_NOT_FOUND: The specified ccID code cannot be found.
INVALID_CONTENT_STATUS: The lending record for this book cannot be found

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Return Book

The borrower returns a specified book to the owner.

Request

POST /store/v2/users/{userId }/books/{ccid}/return
The URL contains the borrower’s user ID and the CCID of the book to be returned.

Errors

USER_NOT_FOUND: The specified user does not exist
CONTENT_NOT_FOUND: The specified ccID code cannot be found.
INVALID_CONTENT_STATUS: The lending record for this book cannot be found

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Gift Book

A specified book is to be given to a specified user.

Request

POST /store/v2/users/{userId}/books/{ccid}/gift
The URL contains the userId of the customer who is giving the book to another person, as well as the CCID of the book involved.

Required POST Data

receiverId: User ID of user who receives the book

Errors

USER_NOT_FOUND: The specified user does not exist
CONTENT_NOT_FOUND: The specified ccID code cannot be found.
INVALID_CONTENT_STATUS: The lending record for this book cannot be found

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Sell Book

With this operation, a user can offer a book for sale.

Request

POST /store/v2/users/{userId}/books/{ccid}/sell
The URL contains the seller’s user ID code and the CCID code of the book that is being offered for sale.

Errors

USER_NOT_FOUND: The specified user does not exist.
CONTENT_NOT_FOUND: The specified ccID code cannot be found.
INVALID_CONTENT_STATUS: The record for this book cannot be found; the seller does not possess the title.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Cancellation of the selling process

As long as the book is not sold, the book can be removed from sale.

Request

POST /store/v2/users/{userId}/books/{ccid}/sell/delete
The URL contains the seller’s user ID and the CCID of the book which is removed from sale.

Errors

USER_NOT_FOUND: The specified user does not exist.
CONTENT_NOT_FOUND: The specified CCID code cannot be found.
INVALID_CONTENT_STATUS: The record for this book cannot be found; the book is not for sale.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Sold Book

The book is actually being sold, and ownership is transferred from the seller to the buyer.
The seller is identified as a parameter with the URL, whereas the buyer is identified as a parameter in the POST data.

Request

POST /store/v2/users/{userId}/books/{ccid}/sold

The URL contains the seller’s user ID code and the CCID of the book which was sold.

Required POST Data

buyerId: The CGP User ID of the buyer.
price: Actual price of the book
currency: ISO code of the currency that is used, such as EUR, USD, or JPY

Errors

USER_NOT_FOUND: The specified user does not exist.
CONTENT_NOT_FOUND: The specified ccID code cannot be found.
INVALID_CONTENT_STATUS: The record for this book cannot be found; the book is not for sale or the buyer already owns the book.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Device API

Get Devices

Gets information about the device(s) of a specified user.

Request

GET /store/v2/users/{userId}/devices
The URL contains the user ID for the user in question.

Response

device: An array of device elements
deviceId: The unique ID of the device in the URMS System
deviceName: A name that can help identify the device

Errors

USER_NOT_FOUND: The specified user does not exist.

Sample Response

{
    "statusCode":0,
    "message":"Success",
    "device":[
        {"deviceId": "1", "deviceName": "AAA's iPhone"},
        {"deviceId": "2", "deviceName": "AAA's Android"}
    ]
}

Update Device Name

The name of a specified user’s device is updated.

Request

POST /store/v2/users/{userId}/devices/{deviceId}
The URL contains the user’s ID code and the device ID for the device to be updated.

Required POST Data

deviceName: The new name of the device

Errors

USER_NOT_FOUND: The specified user does not exist.
DEVICE_NOT_FOUND: The specified device cannot be found.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Delete Device

The device of a specified user will be deleted from CGP. All requests coming from the current session of this device will be denied. The user needs to register the device again to be able to communicate with the CGP server again.

Request

POST /store/v2/users/{userId}/devices/{deviceId}/delete
The URL contains the user’s ID code and the device ID for the device to be deleted.

Errors

USER_NOT_FOUND: The specified user does not exist.
DEVICE_NOT_FOUND: The specified device cannot be found.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

User Group API

Create Group

Creates a new user group and makes the user who creates that group the administrator.

Request

POST /store/v2/users/{userId}/groups
The URL contains the user ID for the user who will be the group administrator.

Required POST Data

groupName: An arbitrary name for the Group

Request

groupId: Group ID, a unique identifier for the group with the URMS system

Errors

USER_NOT_FOUND: The specified user does not exist.

Sample Response

{
    "statusCode": 0,
    "message": "Success",
    "groupId": 100
}

Add User To Group

Add a single user or a list of users to a group.

Request

POST /store/v2/users/{userId}/groups/{groupId}/add
The URL contains the user ID for the group administrator and the group ID. Include the user ID codes for any users you want to add to the Group in the JSON data added to the POST request. If you are adding more than one user ID to the group, list the user ID codes for those users in the JSON file.

Optional POST DATA

userIds: List of userID codes. You can add more than one user to the group in the request if you like.
cleanFlag:

0: Add users in addition to existing users

1: Overwrite users (Existing users are deleted)

Errors

USER_NOT_FOUND: The administrator user or any of the users to add does not exist.
GROUP_NOT_FOUND: The group ID is unknown or the given user is not the administrator of the group.
INVALID_USER_STATUS: One of the users to add is already member of the group.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Remove User From Group

Remove the user from the group.

Request

POST /store/v2/users/{userId}/groups/{groupId}/remove

The URL contains the user ID for the group administrator and the group ID. Include the user ID codes for any users you want to remove from the Group in the JSON data added to the POST request. If you want to remove more than one user ID from the group, list the user ID codes for those users in the JSON file.

Required POST DATA

userIds: List of user ID codes to remove. You can remove more than one user from the group in this request if you like.

Errors

USER_NOT_FOUND: The administrator user or any of the users to remove from the group does not exist.
GROUP_NOT_FOUND: The group ID is unknown or the given user is not the administrator of the group.
INVALID_USER_STATUS: One of the users to remove is not a member of the group.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Add Book To Group

Add a book to the group, making it available to the members of that group. This can only be completed by an administrator.

Request

POST /store/v2/users/{userId}/groups/{groupId}/books

The URL contains the user ID of the group administrator and a group ID.

Required POST DATA

cleanFlag: 0: Add books in addition to existing books.
1: Overwrite books (Existing books are deleted)

Optional POST DATA

ccids: List of CCID codes. You can add more than one book to the group in this command. This allows you to remove all books from the group when used with the cleanFlag.

Errors

USER_NOT_FOUND: The specified user does not exist.
GROUP_NOT_FOUND: The group ID is unknown or the given user is not the administrator of the group.
INVALID_USER_STATUS: The administrator does not possess the book (the book is lent out) or the book is already shared with the group.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Remove Book From Group

Remove a book from the group, making it unavailable to group members.

Request

POST /store/v2/users/{userId}/groups/{groupId}/books/delete

The URL contains the user ID of the group administrator and the group ID.

Required POST DATA

ccids: List of CCID codes. You can remove more than one book from a group using this command.

Errors

USER_NOT_FOUND: The specified user does not exist.
GROUP_NOT_FOUND: The group ID is unknown or the given user is not the administrator of the group.
INVALID_CONTENT_STATUS: The book is currently not shared with the group.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Get Group

Find information about one or more groups belonging to a user.

Request

GET /store/v2/users/{userId}/groups

The URL contains the user ID for the user you seek to find information for, related to groups.

Optional GET DATA

groupId: To set target group ID or to query the details of a single group only.
status: Restrict the returned groups depending on the role of the user in the group:

0:Admin
1:Member
2:All(Default)

Response

group: A list of groups
groupId: Unique identifier of the group
groupName: Group name
userIds: List of members of the group
ccids: List of books shared with the group
adminId: User ID of the administrator of this group
adminFlag: True if the user in the request is the administrator of this group

Errors

USER_NOT_FOUND: The specified user does not exist.

Sample Response

{
    "statusCode": 0,
    "message": "Success",
    "group": [{
        "groupId": 1,
        "groupName": "Group A",
        "userIds":[
            "User A",
            "User B",
            "User C"
        ],
        "ccids":[
            "58802D2CC397CA75",
            "EEE08841E0577C65",
            "D04F753FF86178B4"
        ],
        "adminId": "Admin_A",
        "adminFlag": true
    },
    {
        "groupId": 2,
        "groupName": "Group B",
        "userIds":[
            "User D"
        ],
        "ccids":[
            "58802D2AA367CA75"
        ],
        "adminId": "Admin_B",
        "adminFlag": false
    }]
}

Update Group

Change the name of a group.

Request

POST /store/v2/users/{userId}/groups/{groupId}
The URL contains the user ID for the administrator of the group, and the group ID.

Required POST DATA

groupName: The new group name

Errors

USER_NOT_FOUND: The specified user does not exist.
GROUP_NOT_FOUND: The group ID is unknown or the given user is not the administrator of the group.

Sample Response

{
    "statusCode": 0,
    "message": "Success"
}

Delete Group

Remove a user group. If the target group has any contents, the contents will also be deleted.

Request

POST /store/v2/users/{userId}/groups/{groupId}/delete
The URL contains the user ID for the administrator of the group and the group ID.

Errors

USER_NOT_FOUND: The specified user does not exist.
GROUP_NOT_FOUND: The group ID is unknown or the given user is not the administrator of the group.

Response Sample

{
    "statusCode": 0,
    "message": "Success"
}

Entitlement API

Get Available Entitlements

List all available Entitlements for a specific user including the related Licenses.

Request

GET /store/v2/users/{userid}/entitlements

Required Parameters

userid: The ID code used to register the user with URMS (see Register User)
own: Result includes/excludes books that are owned by the user, boolean value 1 for include, 0 for exclude
lend: Result includes/excludes books that are currently lent to other users, boolean, 1 for include, 0 for exclude
sell:

Result includes/excludes books that are currently being sold by the user, boolean, 1 for include, 0 for exclude

borrow: Result includes/excludes books that are currently borrowed by the user, boolean, 1 for include, 0 for exclude
commonBookshelf: Result includes/excludes books from the common bookshelf, boolean, 1 for include, 0 for exclude

Note: Common bookshelf content will be restricted to the store requesting this information.

group: Result contains books of all groups (the user has joined), boolean, 1 for include, 0 for exclude

Optional

groupId:
If the group flag was set, limit the content to this specific group.
formatType: Only include books of the specified format.
Allowed Values:
0 PDF
1 EPUB2
2 EPUB3

Errors

USER_NOT_FOUND: The specified user does not exist.
ACCESS_DENIED: Web reading is not enabled for this store.

Sample Request

GET /store/v2/users/userXYZ/entitlements?own=1&lend=1&sell=1&borrow=1&commonBookshelf=1&group=1&formatType=2&authString=100-1443615459-ztQvViplf5QRnJsWNRJptzVlmjIEljaAGv4W7SvTPIw%3D

Sample Response

{
    "statusCode":0,
    "message":"Success.",
    "entitlements":[
        {
            "bookStatus": "OWN",
            "source":"BOOKSHELF",
            "license": {
                "expiryTimestamp": null,
                "webReading": true,
                "appReading": true,
                "lendEnabled": true,
                "giftEnabled": true,
                "selfEnabled": true,
                "maximumDownloads": null
            },
            "content": {
                "ccid":"3R6EU3RQS39WJSMMC847GF7A99A5YLMA",
                "externalId":"testNG_fcb3c74f-77b1-4684-88a9-0b13461527cf",
            }
        },
        {
            "bookStatus": "OWN",
            "source":"BOOKSHELF",
            "license": {
                "expiryTimestamp": null,
                "webReading": true,
                "appReading": true,
                "lendEnabled": true,
                "giftEnabled": true,
                "selfEnabled": true,
                "maximumDownloads": null
            },
            "content": {
                "ccid":"3UJG7SBVDCGXN37RSHAFFGQJPXSG4LD4",
                "externalId":"testNG_77e851c2-a039-4b76-8fee-89aec30c71ac",
            }
        }
    ],
    "totalCount":2
}

Get Entitlement Rights

Checks to see if the user is allowed to read a certain book.

Request

GET /store/v2/users/{userid}/entitlements/{ccid}

The URL contains the user ID code for the user, and the book’s CCID.

Response

rights: The calculated Entitlement Rights.
canRead: Boolean flag indicating if the user is allowed to read the book, true or false.

Errors

USER_NOT_FOUND: The specified user does not exist.
CONTENT_NOT_FOUND: The specified CCID cannot be found.
ACCESS_DENIED: Web reading is not enabled for this store.

Sample Request

GET /store/v2/users/userXYZ/entitlements/3FAQHXX8RKVQFQM9U3QJ95EG8YQ5A98Q?authString=100-1443615460-BlEiHUpga6fHJwLDJWGMSM6zRLf%2FlEuV1RjB2hkdS34%3D

Sample Response

{
    "statusCode":0,
    "message":"Success.",
    "rights": [
        {    
            "webRead": true,
            "appRead": true,
            "lend": true,
            "getBack": false,
            "returnBook": false,
            "gift": true,
            "sell": true,
            "cancelSale": false,
            "shareWithGroup": true,
            "removeFromGroup": false, 
        }
     ]                                                
}

Entitlement Management

Introduction

An entitlement describes the relationship between a user and a book, and refers to whether a user is currently eligible to read a given book, either because that user purchased the title, or someone else who owns the book gave or lent that book to the user. An owner is entitled to open and read, lend, or sell the title, or give the title to another.

Every time a relationship between a book and the user is generated, such as when the user buys, lends, or borrows a title, a corresponding entitlement is created within the Common Gateway Platform service.

Entitlements

Entitlement status and transitions

The Entitlement status describes the current connection between the user and the book.

This status can be one of the following:

OWN The user owns the book
LEND The user lent the book to another user (user ID code)
SELL The user offers this book on a flea market
IN_GROUP The user owns the book and has it shared in one of his or her groups (as the group administrator)
BORROW The user has borrowed the book from a store or another user (user ID code)
DELETE The Entitlement relationship was deleted by the owner, by returning the book or giving it to someone else
REVOKED The Entitlement Relation was revoked by the store

Entitlement status changes (Transitions)

Transitions describe the actions which are done with the book. Like a real book, eBooks can be bought, lent, borrowed, sold or returned, and eBooks can also be shared with others in a group.

The entitlement status changes when one of these actions happens. The table below describes how the status of the entitlement changes depending on the transition.

Transition Old Status New Status
The user buys a book none OWN
The user lent the book to another user OWN LEND
The user returns the book to the owner LEND OWN
The user offers this book in a flea market OWN SELL
The user cancels the sale in the flea market SELL OWN
The user binds the book in one of the groups that user is a member of OWN IN_GROUP
The user removes the book from one of these groups IN_GROUP OWN
The user borrows the book from a store or from another user none BORROW
The user returns a borrowed book, or the lending period expires BORROW DELETE
The store revokes the Entitlement Relationship any status REVOKED

Note: The direct connection to the book still exists (as a borrower’s note) when a user lends the book to a friend but the lender will not be able to read the book.

Entitlement Sources

The Entitlement Source describes which way a user is entitled to a book. A user can be granted access to a book from three different sources, from the bookshelf, a common bookshelf, or a group.

BOOKSHELF The user has a direct connection to the book as the owner or borrower.
COMMON_BOOKSHELF The common bookshelf allows a user to group books from different accounts.  If a user owns titles from two different stores, for example, the common bookshelf for that user would hold all of these titles.
GROUP When the user joins a group that user is granted access to all of the books shared with that group.  A common example would be a student enrolling in a class.  The student would have rights to access any books shared with that class.

Licenses

Licenses are a predefined set of rights stored in the database.  Rights are calculated in real-time and display the current level of permissions a user has related to a book based on the Entitlement status, the source of the entitlement, and previous uses.

Note: When user is granted rights to a book, the store template generates a new license for that book. If the license is changed later it has no effect on existing entitlement licenses.

License Types

Consider the differences between Content licenses, Store license templates, and Entitlement Licenses.

Content Licenses (Distributor) Content licenses are connected to the encrypted book and define the set of rights available for that book. Content licenses are defined by the distributor/publisher of the book during packaging of the product. The distributor defines the outer bounds of Store licenses and Entitlement licenses.
Store License Templates (Store) Store license templates define the set of rights set for a particular entitlement. Store licenses templates are generated by the store and not restricted to a particular book. This applies when a store entitles a user to a book, such as when the user buys or borrows a title.
Entitlement Rights (Users) Entitlement rights define the rights set for a particular entitlement. Entitlement rights are generated by the Common Gateway Platform service on the fly when a store grants a user entitlement to a book, such as when the user buys or borrows a title.  The Entitlement rights are calculated from an overlap of Store license template and content license.

License Settings

Note: This license settings object displays the current rights the user has to the book based on the current book Status.

When generating a relationship between the user and the book, such as when the user buys or borrows a title, the new user will be entitled including a copy of all Rights set in the License.

The following Rights are available:

Access Rights Describes if the book can be read via Reader application or using Web reading.
webRead, display the app online via web reader
appRead, download and display the app in the reader
Friend-2-Friend Describes operations between users.
lendEnabled, lend the book to a friend
giftEnabled, give the book away as a present
sellEnabled, sell the book on a flea market
Transition changes Describes if transactions can be made on the entitlement.
Lend, enable the user to lend the book
getBack, enable the user to get the book back after lending it to another
returnBook, enable the user to return the book to the lender
sell, enable the user to sell or re-sell the book
cancelSale, enable the user to cancel the sale of the book
shareWithGroup,  enable the user to share the book within a group, such as a college class
removeFromGroup, enable the user to remove the book from a group
Time based usage Describes the amount of time that a book is available, as in the lending period for a borrowed title
expiryTimestamp, date that the book will expire and no longer be available to the user
expiryDays, the number of days which can be set until the expiration date or timestamp
Unit based usage Describe the number of uses for unit based features.
maximumDownloads, the total number of times the book may be downloaded
downloadCounter, the number of the most recent download

Entitlement rights

When the user is granted an entitlement to an eBook, an entitlement right is created based on the store license template.

Access Rights Describes if the book can be read via Reader application or a browser based on Entitlement Status:
webRead, display the app online via a web reader
appRead, download and display the app in the reader
Transition changes Describes if transactions can be made on the entitlement based on Entitlement Status and Entitlement Source:
lend, user can lend the book
getBack, the user can get the book back after lending it to another
returnBook, the user can return the book to the lender
sell, the user can sell or re-sell the book
cancelSale, the user can cancel the sale of a book
shareWithGroup, the user can share the book with a group, such as a college class
removeFromGroup, the user can remove the book from a group
Time based usage Describes the timeframe a book is accessible if a Time Based Right is set. For example, if a user borrows a book from a store, commonly the book will have a lending period that ends with an expiration date.
expiryTimestamp, the timestamp for the expiration date, defining the time that the book is available to the user