Working with Projects

Working with Projects

API Key Type Required: Publishing API

The primary use case for the publishing API is to create new projects and make them available for purchase either through Lulu.com or one of our retail channels. This set of APIs also allows developers to retrieve information about existing projects. Before using any API in this set, the user must be authenticated.

The publish API does not adhere to our standard API conventions. See Publish API Set Conventions for details on how these API calls differ from the standard.

Create

Purpose

Create a new project using files that have already been uploaded to your account. See uploading a file for details about providing files to publish.

Upon success, you will be provided a unique identifier which can be used to locate the book on Lulu. It will be at

http://www.lulu.com/content/{content_id}

POST Arguments

  • api_key -- Your api key for the Publish API.
  • auth_user -- The Lulu.com account you used with the authenticator API to login for this session.
  • auth_token -- The auth token returned from the authenticator API.
  • project -- A JSON Representation of the project.

Endpoint

https://apps.lulu.com/api/publish/v1/create

JSON Response

The response to this request is a JSON structure with the content_id of the created project. This content_id is a unique identifier which can be used to reference the project in future API requests.

{
    'content_id'  : integer
}

Errors

All errors are displayed in the following format
{
    "error_type": "LApiPublishInvalidDocumentException", 
    "error_value": "Your document has too few pages for the print options you have chosen."
}

To get a human-readable string for the error, look in the error_value field.

Read

Purpose

Retrieve the project structure for an existing project

GET Arguments

  • content_id -- The id of the project to retrieve.

POST Arguments

  • api_key -- Your api key for the Publish API.
  • auth_user -- The Lulu.com account you used with the authenticator API to login for this session.
  • auth_token -- The auth token returned from the authenticator API.

Endpoint

https://apps.lulu.com/api/publish/v1/read/id/${content_id}

JSON Response

The response to this request is the JSON representation of the requested project.

{
  "project" : {
    "bibliography" : {
      "category" : 1,
      "publisher" : "Lulu.com",
      "copyright_citation" : "Smith's Publishing",
      "description" : "Greco-Roman wrestling is a popular style of wrestling that is practiced worldwide. Distinguished primarily by the rule that forbids holds below the waist, the sport emphasizes upper body strength and throws.",
      "license" : "Public Domain",
      "title" : "A Poor Man's Guide to Greco-Roman Wrestling",
      "language" : "EN",
      "copyright_year" : 2011,
      "edition" : "First",
      "country_code" : "US",
      "authors" : [ {
        "first_name" : "John",
        "last_name" : "Smith"
      }, {
        "first_name" : "Bob",
        "last_name" : "Jones"
      } ],
      "keywords" : [ "wrestling", "greco-roman", "sport guides" ]
    },
    "program_code" : null,
    "access" : "public",
    "drm" : false,
    "allow_ratings" : true,
    "project_type" : "softcover",
    "isbn" : {
      "publisher" : "Lulu.com",
      "intent" : "assigned",
      "number" : "9780557016099",
      "contact_info" : {
        "city" : "Raleigh",
        "name" : "Lulu.com",
        "country" : "US",
        "street2" : "",
        "phone" : "",
        "state" : "NC",
        "postal_code" : "27607",
        "street1" : "3101 Hillsborough St."
      }
    },
    "distribution" : [ "lulu_marketplace" ],
    "content_id" : 79628203,
    "physical_attributes" : {
      "color" : false,
      "trim_size" : "US_TRADE",
      "binding_type" : "perfect",
      "paper_type" : "regular"
    },
    "pricing" : [ {
      "total_price" : 15,
      "product" : "print",
      "royalty" : 7.44,
      "currency_code" : "USD",
      "discount_percent" : 0
    } ]
  }
}

Errors

All errors are displayed in the following format
{
    "error_type": "LApiPublishInvalidDocumentException", 
    "error_value": "Your document has too few pages for the print options you have chosen." 
}
To get a human-readable string for the error, look in the error_value field.

List

Purpose

Retrieve a list of all content IDs owned by the account referenced through the auth_token.

POST Arguments

  • api_key -- Your api key for the Publish API.
  • auth_user -- The Lulu.com account you used with the authenticator API to login for this session.
  • auth_token -- The auth token returned from the authenticator API.

Endpoint

https://apps.lulu.com/api/publish/v1/list

JSON Response

The response to this request is a list of the project IDs owned by the account. If there are no projects in this account, the list will be empty.

{
  "content_ids" : [ 1234567, 918324, 87481723, 79628203 ]
}

Errors

All errors are displayed in the following format
{
    "error_type": "LApiPublishInvalidDocumentException", 
    "error_value": "Your document has too few pages for the print options you have chosen."
}
To get a human-readable string for the error, look in the error_value field.

Update

Purpose

Modify the metadata for a project that already exists. Changes will create a new revision with the same content ID. This API accepts either a partial or full project object. If a partial project is submitted, only those fields that were submitted are modified. This allows you to send the same update commands for multiple projects, without performing reads on each of them.

Optionally, the file names of previously uploaded files can be provided in order to update the interior and cover documents. Note that either neither or both of these file must be supplied, even if only one of them is changing.

A small number of fields can not be modified with this command:

  • content_id -- This value is assigned by the system and cannot be changed or set by the user.
  • project_type -- Changing the project type, for example from softcover to hardcover, is not supported, you must create a second project.
  • isbn -- Once an ISBN has been assigned to a book, the information (including associated publisher information) cannot be updated. A book that does not have an ISBN, however, can have one added through an update call.

GET Arguments

  • content_id -- The id of the project to retrieve.

POST Arguments

  • api_key -- Your api key for the Publish API.
  • auth_user -- The Lulu.com account you used with the authenticator API to login for this session.
  • auth_token -- The auth token returned from the authenticator API.
  • project -- A JSON Representation of the project.

Endpoint

https://apps.lulu.com/api/publish/v1/update/id/${content_id}

JSON Response

{
  "project" : {
    "bibliography" : {
      "category" : 1,
      "publisher" : "Lulu.com",
      "copyright_citation" : "Smith's Publishing",
      "description" : "Greco-Roman wrestling is a popular style of wrestling that is practiced worldwide. Distinguished primarily by the rule that forbids holds below the waist, the sport emphasizes upper body strength and throws.",
      "license" : "Public Domain",
      "title" : "A Poor Man's Guide to Greco-Roman Wrestling",
      "language" : "EN",
      "copyright_year" : 2011,
      "edition" : "Second Edition",
      "country_code" : "US",
      "authors" : [ {
        "first_name" : "John",
        "last_name" : "Smith"
      }, {
        "first_name" : "Bob",
        "last_name" : "Jones"
      } ],
      "keywords" : [ "wrestling", "greco-roman", "sport guides" ]
    },
    "program_code" : null,
    "access" : "public",
    "drm" : false,
    "allow_ratings" : true,
    "project_type" : "softcover",
    "isbn" : {
      "publisher" : "Lulu.com",
      "intent" : "assigned",
      "number" : "9780557016099",
      "contact_info" : {
        "city" : "Raleigh",
        "name" : "Lulu.com",
        "country" : "US",
        "street2" : "",
        "phone" : "",
        "state" : "NC",
        "postal_code" : "27607",
        "street1" : "3101 Hillsborough St."
      }
    },
    "distribution" : [ "lulu_marketplace", "retail_channels" ],
    "content_id" : 79628203,
    "physical_attributes" : {
      "color" : false,
      "trim_size" : "US_TRADE",
      "binding_type" : "perfect",
      "paper_type" : "regular"
    },
    "pricing" : [ {
      "total_price" : 100,
      "product" : "print",
      "royalty" : 38.29,
      "currency_code" : "GBP",
      "discount_percent" : 50
    } ]
  }
}

Errors

All errors are displayed in the following format 
{
    "error_type": "LApiPublishInvalidDocumentException", 
    "error_value": "Your document has too few pages for the print options you have chosen." 
}
To get a human-readable string for the error, look in the error_value field.

Delete

Purpose

Delete or retire a project that is no longer needed. Projects that have never been purchased will be removed from the Lulu system completely. If the project has already been purchased by anybody, it cannot be deleted. Instead, this method will retire the project. Retired projects can no longer be purchased, but existing users will have access to what they purchased (in the case of downloads) and previews and source documents will not be deleted.

GET Arguments

  • content_id -- The id of the project to delete.

POST Arguments

  • api_key -- Your api key for the Publish API.
  • auth_user -- The Lulu.com account you used with the authenticator API to login for this session.
  • auth_token -- The auth token returned from the authenticator API.

Endpoint

https://apps.lulu.com/api/publish/v1/delete/id/${content_id}

JSON Response

[ ]

Errors

All errors are displayed in the following format
{
    "error_type": "LApiPublishInvalidDocumentException", 
    "error_value": "Your document has too few pages for the print options you have chosen." 
}
To get a human-readable string for the error, look in the error_value field.

Get Base Cost

Purpose

When pricing the project, it is important to know the minimum cost. Your project cannot be priced less than the value returned by this method. This value will cover the price of printing for physical books and hosting and DRM fees for eBooks. The difference between this value and what you price the book dictates how much money paid for each sale. To see the computation in action, use this cost calculator.

Note: The base cost returned by this method only applies if you wish to charge money for your eBook. If you make your eBook free, then you can ignore this call.

POST Arguments

  • api_key -- Your api key for the Publish API.
  • auth_user -- The Lulu.com account you used with the authenticator API to login for this session.
  • auth_token -- The auth token returned from the authenticator API.
  • project -- A JSON Representation of the project. This does not need to be a complete project object. The only required fields are: project_type, and either physical attributes (books) or drm (eBooks).
  • page_count -- The number of pages in the book. This is required for physical books, but is ignored for eBooks.

Endpoint

https://apps.lulu.com/api/publish/v1/base_cost

JSON Response

The response to this API is a JSON data structure providing the base cost for the book and the currency in which the cost is calculated. This API uses the currency set on the user's account.

{
    "cost"     : "7.60",
    "currency" : "USD"
}

Errors

All errors are displayed in the following format
{
    "error_type": "LApiPublishInvalidDocumentException", 
    "error_value": "Your document has too few pages for the print options you have chosen." 
}
To get a human-readable string for the error, look in the error_value field.

Downloading Content files

Purpose

After creating your project, it is often useful to download the exact PDF that Lulu will print. This PDF can be used to create preview solutions, or to allow your users to retrieve their files.

GET Arguments

  • content_id -- The id of the project to retrieve.
  • content_type -- Either "cover" or "contents", specifies the content you want to download.

POST Arguments

  • api_key -- Your api key for the Publish API.
  • auth_user -- The Lulu.com account you used with the authenticator API to login for this session.
  • auth_token -- The auth token returned from the authenticator API.

Endpoint

https://apps.lulu.com/api/publish/v1/download/id/${content_id}/what/${content_type}

JSON Response

The response to this API is the file that you have requested.

Errors

All errors are displayed in the following format
{
    "error_type": "LApiPublishInvalidDocumentException", 
    "error_value": "Your document has too few pages for the print options you have chosen." 
}
To get a human-readable string for the error, look in the error_value field.

version 7 as of 2 years ago by Ryan Bloom

0 Comments

Please sign in to post a comment.