CloudPublish

CloudPublish API

The CloudPublish API is a REST-style interface to the CloudPublish platform, outputing data in JSON format. The purpose of the API is to allow a publisher to create a front-end to the CloudPublish system. The front-end can be as simple as a catalogue listing or as complex as an ecommerce book-store.

Demonstration and example code

A simple example site, for a fictitious publisher, is available here: http://www.cloudpublishdemo.co.uk. The code (PHP) used to create this site includes a CloudPublishConnector class that is intended to make integration more straightforward.

The demonstration code is available to download from within the CloudPublish admin area, under "API Examples".

It is important to note a few things that the CloudPublish API does not do:

  1. There is no customer/user database provided, as such. It is expected that you maintain your own customer-facing systems / website, and then supply a unique customer identifier to the API when referring to a specific customer (e.g., retrieving subscription data for a customer). This identifier would typically be the same ID or unique customer number as used in your own customer account database, thereby enabling you to link records effectively.
  2. The batch processing of PDFs into ebooks is not done via the API, although you can check the progress of ebooks by using the BookGetAll and BookGet methods.

For more information, please see the CloudPublish support pages.

API Documentation

Connection and authentication

Results format

Testing

Catalogue: General

These methods are applicable to more than one type of item.

Get subjects data

Expand a subject

Catalogue: Books

A book typically represents a single ebook.

Get book data (all books)

Get book data (single book)

Get Table of Contents (single book)

Get citation for book(s)

Get imprints data

Get imprint details (single imprint)

Get series data

Get authors data

Get author details (single author)

Catalogue: Chapters

A chapter consists of a fragment of a book that is already in your catalogue, defined by a page range within that book. While books are added by sending ONIX metadata, chapters are created via the API. Chapters are currently only available via the online eReader.

Get chapter data (all chapters)

Get chapter data (single chapter)

Create a chapter

Update a chapter

Delete a chapter

Catalogue: Journals

Journals are handled slightly differently to books. There are several levels in the structure:

  • Journal: An entire publication. Does not exist as a readable item.
  • Issue: A single issue of a Journal. Can exist as a readable item, or as a container for Articles.
  • Article: A single article within a single Issue of a Journal. Can exist as a readable item or as a metadata container for use with Issue.
  • Reference: A single reference or endnote, associated with a single Article.

Therefore, a Journal may have multiple Issues, each of which may have multiple Articles, each of which may have multiple References.

The corresponding files you upload depend on whether you want to provide access by issue, or by article, or both. In any case you will need to upload issues and/or articles with unique filenames.

Important: In order to ensure uniqueness of your filenames, you must incorporate an ISSN or other identifier unique to your organisation. For books, the ISBN system accomplishes this for you. We recommend naming files as follows:

  • Issue: ISSNvolXissY.pdf (where X and Y are integers)
  • Article: ISSNvolXissYpZ.pdf (where Z is the page number of the article)

Get journal data (all journals)

Get journal data (single journal)

Get journal volume data

Get journal issue data (all issues)

Get journal issue data (single issue)

Get journal article data (all articles)

Get journal article data (single article)

Get a reference in citation format

Get all articles by an author

Get all references to an author

Collections

Collections are simply groups of the same type of item. They are typically used to group items for sales purposes, e.g. by subject. A collection can contain items of one (and only one) of the following types:

  • Books
  • Journals (i.e. complete journals)
  • Journal issues (i.e. single issues)
  • Journal articles

Get collections data

Get collection details (single collection)

Accessing items for reading

Items can be accessed for online reading (using CloudPublish CloudReader) for download (PDF via Adobe Digital Editions with Adobe CRM).

Access an item (download or online)

Get number of current readers for an item

Search

Searches are conducted either across the catalogue, searching either catalogue metadata or within the text of specific items. Searches can be saved against a customer identifier.

  • /Search is for searching catalogue metadata, using keyword matching
  • /SearchText is for searching within the text of one or more items, or your entire catalogue, using natural language matching

Natural language matching allows for the search term to be enclosed in double-quotes (") to prioritise a seach for the exact phrase.

Searches conducted via /Search can be saved, using /SearchSave, but fulltext searches via /SearchText cannot be saved.

Search catalogue

Save a search for a customer

Search within the text of items

Retrieve a customer's saved searches

Run a saved search

Orders

An order is a submitted cart. When processed, it generates subscriptions and transactions.

Create an order

Get order(s)

Update an order

Delete an order

Update an order's items

Delete an item from an order

Process an order (convert to subscriptions)

Subscriptions

A subscription entitles a customer to access one or more copies of a book. It can be created directly or by processing an order. Note that creating a subscription directly also creates a corresponding transaction.

It is possible for a customer to have more than one subscription to a given book. In this case, the /CustomerSubscriptionCheck method will check all matching subscription, and will return affirmatively if at least one is valid/current for the book.

Create a subscription

Get subscriptions data

Get a subscription

Update a subscription

Delete a subscription

Transactions

A Transaction is generated when an order is processed or when a subscription is created directly.

Get transactions data

Get single transaction details

Manually create a transaction

Update a transaction

Delete a transaction

Update a transaction's items

Delete an item from a transaction

Customers

A customer is a single actor within your customer-base. In CloudPublish, customers are not described in full, but merely by unique identifier, which should correspond to the complete customer record in your own systems.

Identify a customer

Retrieve customer details

Get customer-specific order information

Get customer-specific subscription information

Check whether a customer has a subscription to an item

Check whether a customer can access an item

Get customer-specific transaction information

Get customer usage statistics (excl. COUNTER stats)

Get statistical reports in COUNTER format.

Lists

A list is simply an arbitrary list of items, typically created by an end-user (for example, a search result, or a "read later" list, etc.)

Create a list

Update a list

Delete a list

Get many lists

Get a single list

Content Management

The CloudPublish Admin Tool allows you to create content "snippets" which are intended to be displayed on any related landing page on your site. Use the API to retrieve them.

Retrieve CMS Content