Using the ISSUU API to upload and delete publications

Issuu is a document sharing and publishing service that allows users to convert any type of publication file (PDF, word, …) to a visually appealing media viewer, which presents the content like a real book with an unique “page flip” effect.

Today I am going to explain the basics of the Issuu API to learn how to upload and delete publications in Ruby.

First of all, we need to get the public and private API keys, which can be obtained by registering at the same issuu.com site.

To exchange information with Issuu using this API we will have to sign every petition we make.

Signing data

According to Issuu API specification (July 2010), the steps involved in signing an HTTP request are as follows:

  1. Sort request parameters alphabetically
      (e.g. foo=1, bar=2 sorts to bar=2, foo=1)
  2. Concatenate in order your API secret key and request name-value pairs (e.g. SECRETbar2baz3foo1)
  3. Calculate the signature as the MD5 hash of this string
  4. Include the signature parameter in the request encoded as lowercase HEX (e.g. signature=7431d31140cf412ab5caa73586d6324a)

Here is the representation of this algorithm in Ruby:

Where params contains all the parameters defined as a key/value hash. eg {access => private, :action => issuu.document.upload, … }, and API_SECRET is the api secret key defined somewhere as a constant.

Uploading a document

Because of the cumbersome way that binary file upload works in Net::HTTP library (you have to implement it all yourself), we decided to use a gem called “Multipart” which allowed us to mix the binary file with the rest of the parameters.

Let’s take a look at the code:

To upload a publication to Issuu each request must be sent to http://upload.issuu.com/1_0? using the POST method. First we prepare the file with the Multipart’s object UploadIO. 

Then we set the parameters that specifies the type of petition we will make. The most important fields are action, format and name:

  • action: the upload action. This field will change when deleting a file.
  • format: specifies the language of the response (JSON or XML).
  • name: is the unique url of our publication.

Now we can sent the POST request using another Multipart gem method joining the “file” and “signature” parameters.

After sending the request, we can easily get the response status by decoding the JSON text returned by Issuu. If all goes well, we should receive an “ok” status followed by a limited number of response parameters, with information about the document which has been created.

Now it’s a good idea to store the documentID so we can delete it later on.

Deleting a publication

Deleting a publication is fairly easy, we can use GET or POST method. We will use the second.

Here it is the code:

Note that we changed the url to http://api.issuu.com/1_0? and the action to issuu.document.delete

We can set the files to be deleted in the names field.

Other considerations

Because Issuu does not support file overwriting, we will have to delete each file before trying to upload it. You may be asking we could also make a request to check if the file is uploaded, but surprisingly you cannot make a request by documentID nor document name.

 

One thought on “Using the ISSUU API to upload and delete publications

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>