Working with Covers

Purpose

This API begins a new conversion job which will create a PDF suitable for use as a book cover.  Before calling this API, you may upload the source documents using the file management API and retrieve the file IDs for use on your cover.

Request Type:  POST

QUERY_STRING

• api_key -- Your api key for the Publication API.
• auth_token -- The auth token returned from the authenticator API.

POST Arguments

• An XML or JSON representation of a cover conversion manifest, specified by the Content-Type HTTP header.

Endpoint

https://apps.lulu.com/api/create/v1/coverconversion?api_key={your api key}&auth_token={authentication token}

Response

An XML or JSON representation of a cover conversion status.

For XML, set the HTTP header Accept to application/xml.  For JSON, set the Accept header to application/json.

Errors

On errors, the HTTP response will not be 200.  The notifications structure will contain a human readable explanation of the error as well as an error code.  If the cover conversion method returns an error, then the conversion is not begun.  You must fix the error and re-submit the cover conversion request.  There are 5 possible validation errors:

• Invalid template id specified
• Unable to retrieve image file
• Invalid color code supplied
• Invalid spine width specified
• Cumulative size of input files exceeds 2G

Purpose

Because cover conversion is an asynchronous process, it is possible to check the status of your cover conversion at any time.  This allows you to keep abreast of what is happening with your files.

Request Type:  GET

QUERY_STRING

• coverConversionId -- The conversion for which you are requesting information.
• api_key -- Your api key for the Publication API.
• auth_token -- The auth token returned from the authenticator API.

Endpoint

https://apps.lulu.com/api/create/v1/coverconversion/{coverConversionId}?api_key={your api key}&auth_token={authentication token}

On errors, the HTTP response will not be 200. The notifications structure will contain a human readable explanation of the error as well as an error code. If there is an error while converting files, the cover conversion will be termininated, and must be resubmited. There are 5 possible cover conversion errors:

• Input mime type cannot be handled
• Conversion between provided input and output mime types not supported
• Provided file is corrupt
• Provided file is encrypted or locked
• Conversion would result in output file exceeding 2G

Purpose

Calculate the exact size required for the cover and spine width for the book you are generating the cover for.  This must be done on a book by book basis, as the exact number of pages in the book will dictate the exact spine width.

Note: This API call is intended primarily for discovering the width of the spine of a book and how that affects the total cover size. As such it will only work with binding types that have a spine (perfect, jacket-hardcover, casewrap-hardcover). Other types of books should have a cover PDF with a height equal to that of the trim size, and a width twice the width of the trim size.

GET Arguments

• api_key -- Your api key for the Publication API.

POST Arguments

• An XML or JSON representation of the physical properties of the book.

Endpoint

https://apps.lulu.com/api/create/v1/getcoversize/?api_key={your api key}

Response

An XML or JSON structure representing the exact cover dimensions.  If the call is successful, then the status field will be 200.

{
    "coverSizeData" : {
      "fullCoverDimension" : {
        "width" : {
          "valueInPoints" : 646.22,
          "valueInInches" : 8.96
        },
        "height" : {
          "valueInPoints" : 513.0,
          "valueInInches" : 7.13
        }
      },
      "spineWidth" : {
        "valueInPoints" : 16.22,
        "valueInInches" : 0.23
      },
      "spineIndentation" : {
        "length" : {
          "valueInPoints" : 315.0,
          "valueInInches" : 4.38
        },
        "orientation" : "FROM_LEFT"
      }
   },
   "details" : null,
   "status" : 200  
} 

On errors, the HTTP response will not be 200. The notifications structure will contain a human readable explanation of the error as well as an error code.  There are 3 possible cover size calculation errors:

• Input mime type cannot be handled
• An invalid combination of physical properties is supplied
• XML or JSON input is malformed