Working with Files

API Key Type Required:  Publishing API

The most important artifacts for creating a book or eBook are the files that make up the book block and cover.

Purpose

Information about a specific file in the system can be retrieved using a GET request for that file ID.

Endpoint

GET https://apps.lulu.com/api/create/v1/file/{id}

Query String Arguments

The arguments related to authentication and authorization must go into the query string. These include

• api_key -- Your Publishing API key.
• auth_token -- The authentication token returned from the authentication API.

Response

A file information retrieval will return the metadata for the file as stored in the system. This includes properties such as file type, size, name, and time of creation. See below for examples.

JSON

{
  "fileId": 979,
  "createdDate": "2011-05-24T09:21:45",
  "mimeType": "application/pdf",
  "name": "interior.pdf",
  "size": 225771,
  "updatedDate": "2011-05-24T09:21:45"
}

XML

<file>
  <fileId>979</fileId>
  <createdDate>2011-05-24T09:21:45</createdDate>
  <mimeType>application/pdf</mimeType>
  <name>interior.pdf</name>
  <size>225771</size>
  <updatedDate>2011-05-24T09:21:45</updatedDate>
</file>

Errors

• HTTP 404 Not Found (1000000001) -- the requested file does not exist.
• HTTP 403 Forbidden (1000000002) -- the provided authentication token does not correspond to a valid session.
• HTTP 500 Internal Server Error (1000020001) -- an unexpected error has occurred. Ensure that the request is not malformed is some way.

Purpose

This call will list the files that are stored in the system. The file information returned is equivalent to that returned by a single file retrieval. The list call supports pagination via limit and offset parameters, as well as filtering based on mime type and file name.

Endpoint

GET https://apps.lulu.com/api/create/v1/file

Query String Arguments

The arguments related to authentication and authorization must go into the query string. These include

• api_key -- Your Publishing API key.
• auth_token -- The authentication token returned from the authentication API.

In addition, inputs to modify the results of the list call are included in the query string. These include

Response

The response to a list call is a data structure that contains the parameters that were used as inputs (filters and pagination parameters) and an array of results. Note that the pagination portion of the list response includes a total number of results in order to aid in the generation of a pagination interface. See below for examples of list responses.

JSON

Assuming a request of

GET /api/create/v1/file?mimeType=application/pdf&limit=1&offset=20&auth_token={token}&api_key={key}

{
    "query": {
        "filters": {
            "mimeType": "application/pdf"
        },
        "sortFields": [
            "-createdDate"
        ],
        "pagination": {
            "limit": 1,
            "offset": 20,
            "totalResults": 226
        }
    },
    "files": [
        {
            "createdDate": "2011-05-24T09:21:45",
            "fileId": 979,
            "mimeType": "application/pdf",
            "name": "60pg_6x9.pdf",
            "size": 225771,
            "updatedDate": "2011-05-24T09:21:45"
        }
    ]
}

XML

Assuming a request of

GET /api/create/v1/file?mimeType=application/pdf&limit=5&offset=0&auth_token={token}&api_key={key}

<list>
    <query>
        <filters>
            <mimeType>application/pdf</mimeType>
        </filters>
        <sortFields>
            <sortField>-createdDate</sortField>
        </sortFields>
        <pagination>
            <offset>0</offset>
            <limit>5</limit>
            <totalResults>37</totalResults>
        </pagination>
    </query>
    <files>
        <!-- ... 5 files ... -->
    </files>
</list>

Response Without Parameters

Assuming a request with no parameters aside from the api key and authentication token

GET /api/create/v1/file?auth_token={token}&api_key={key}

<list>
    <query>
        <sortFields>
            <sortField>-createdDate</sortField>
        </sortFields>
        <pagination>
            <offset>0</offset>
            <limit>10</limit>
            <totalResults>43</totalResults>
        </pagination>
    </query>
    <files>
        <!-- ... 10 files ... -->
    </files>
</list>

Errors

• HTTP 400 Bad Request (1000010008) -- the request is invalid. This can occur if a non-integer is used in the limit or offset parameters or if an invalid filtering field is provided.
• HTTP 403 Forbidden (1000000002) -- the provided authentication token does not correspond to a valid session.
• HTTP 500 Internal Server Error (1000020001) -- an unexpected error has occurred. Ensure that the request is not malformed is some way.

Purpose

To insert a new file into the system, you must perform a multipart/form-data file upload. This will save the file data, along with some metadata about the file, into our system for future use in a project. A file that has been stored in our file management API can be used as an interior or cover document, or can be used as an input into document conversion and cover generation calls.

Endpoint

POST https://transfer.lulu.com/api/create/v1/file

This is a different hostname from all other APIs. If you attempt to upload using the https://apps.lulu.com/ hostname, the request will fail.

Query String Arguments

The arguments related to authentication and authorization must go into the query string. These include

• api_key -- Your Publishing API key.
• auth_token -- The authentication token returned from the authentication API.

POST Body

The post body must be provided using a content type of multipart/form-data. Only a single file can be supplied and it must be the first and only input in the post body. It is recommended that you rely on a library to generate such a request rather than coding one by hand, but for reference an example of such post body is provided here:

POST /api/create/v1/file HTTP/1.1
User-Agent: curl 7.15.5 (x86_64-redhat-linux-gnu) libcurl/7.15.5 OpenSSL/0.9.8b
Host: transfer.lulu.com
Content-Length: 32
Content-Type: multipart/form-data; boundary=gc0p4Jq0M2Yt08jU534c0p

--gc0p4Jq0M2Yt08jU534c0p
Content-Disposition: form-data; name="fileupload"; filename="test.html"
Content-Type: text/html

<body>file contents are here</body>


--gc0p4Jq0M2Yt08jU534c0p--

Response

An upload call will respond with the file metadata that has been stored in the system. This is equivalent to the response of a subsequent GET of that file.

JSON

{
  "fileId": 979,
  "createdDate": "2011-05-24T09:21:45",
  "mimeType": "application/pdf",
  "name": "interior.pdf",
  "size": 225771,
  "updatedDate": "2011-05-24T09:21:45"
}

XML

<file>
  <fileId>979</fileId>
  <createdDate>2011-05-24T09:21:45</createdDate>
  <mimeType>application/pdf</mimeType>
  <name>interior.pdf</name>
  <size>225771</size>
  <updatedDate>2011-05-24T09:21:45</updatedDate>
</file>

Errors

• HTTP 400 Bad Request (1000010008) -- the request is invalid. This can occur if there is no file was included in the request or if the multipart post body is in error.
• HTTP 403 Forbidden (1000000002) -- the provided authentication token does not correspond to a valid session.
• HTTP 500 Internal Server Error (1000020001) -- an unexpected error has occurred. Ensure that the request is not malformed is some way.

Purpose

A file in the file API, whether it was been uploaded directly or generated by a document conversion, can be downloaded using a request for the file data.

Endpoint

GET https://transfer.lulu.com/api/create/v1/file/{id}/data

As with uploads, this is a different hostname from all other APIs. If you attempt to upload using the https://apps.lulu.com/ hostname, the request will fail.

Query String Arguments

The arguments related to authentication and authorization must go into the query string. These include

• api_key -- Your Publishing API key.
• auth_token -- The authentication token returned from the authentication API.

Response

If authentication succeeds, the response will include the file data, with a header of 'Content-Disposition: attachment; filename="{the filename as uploaded}"'.

Errors

• HTTP 404 Not Found (1000000001) -- the requested file does not exist.
• HTTP 403 Forbidden (1000000002) -- the provided authentication token does not correspond to a valid session.
• HTTP 500 Internal Server Error (1000020001) -- an unexpected error has occurred. Ensure that the request is not malformed is some way.