Publitas e-docconverter API User Guide Copyright 2004-2010 Publitas Consulting Services B.V. Page 1 of 11
Version control Version Date Author description 1.0 01-04-2010 Dieudon Egstorf Final version 1.0 1.1 09-06-2010 Khalil Seyedmehdi Added additional supported doctypes Copyright 2004-2010 Publitas Consulting Services B.V. Page 2 of 11
Index 1 Introduction... 4 2 The API... 5 2.1 Which method for which action?... 5 2.2 Response formats... 5 2.3 Ping back formats... 5 3 Creating and updating conversion jobs... 6 3.1 Create a new conversion job... 6 3.1.1 Input parameters... 6 3.1.2 Output... 6 3.1.3 Example code... 7 3.2 Update existing conversion job... 7 3.2.1 Input parameters... 7 3.2.2 Output... 7 3.2.3 Example code... 7 4 Get information about a conversion job... 8 4.1 Get conversion job details in JSON format... 8 4.1.1 Input parameters... 8 4.1.2 Output JSON... 8 4.2 Get conversion job details in XML format... 9 4.2.1 Input parameters... 9 4.2.2 Output XML... 9 5 Canceling a conversion job... 10 5.1 Input parameters... 10 5.2 Example code... 10 6 Downloading conversion job results... 11 Copyright 2004-2010 Publitas Consulting Services B.V. Page 3 of 11
1 Introduction Publitas e-docconverter is a web service that converts document files to online accessible formats, like flash (swf) and/or static images (jpg). Besides converting the documents, images and text can be extracted from the documents as well. To convert a document with the Publitas e-docconverter a conversion job has to be created using the API. Each conversion job contains all information and tracks the status about the conversion of one single document. The Publitas e-docconverter provides a simple API that allows conversion jobs to be created, read, modified and cancelled. The following block diagram shows how the Publitas e-docconverter interacts with 3rd party applications. This diagram does not contain detailed interactions and processes; its purpose is only to give a general overview. 3 rd party application document conversion job request Publitas e-docconverter Return job request success or fail Ping back when document conversion process is finished success or fail Fetch back document job results package Copyright 2004-2010 Publitas Consulting Services B.V. Page 4 of 11
2 The API The Publitas e-docconverter API is based on REST principles, so what you just have to do is an HTTP request to the right resource and the right describing method. To use the Publitas e-docconverter API, you must be authenticated via Basic Auth. API calls will be made by sending http requests to a URL that will have the following form: http://<edoc-host-url>/converter/rest/<class-name> The <edoc-host-url> will be provided by Publitas, together with the credentials (username/password). 2.1 Which method for which action? GET: Get information about a conversion job POST : Create or modify a conversion job DELETE : Delete a conversion job 2.2 Response formats Supported formats for getting conversion job details are JSON and XML. The default response format is JSON. Add &format=xml to the http request URL to receive the response in XML format. Example how to get response in JSON: http://<edoc-host-url>/converter/rest/jobs?conversionjobid=<job id> Example how to get response in XML: http://<edoc-host-url>/converter/rest/jobs?conversionjobid=<job id>&format=xml 2.3 Ping back formats The Publitas e-docconverter posts back the status of the conversion job to URL s given as parameters creating the job. The ping back format is JSON and available in the POST. The JSON is build up as followed: {"id":<jobid>,"status":<status>} Example: {"id":"8abfb5021bb23383011bb23dc3e70004","status":"finished"} Copyright 2004-2010 Publitas Consulting Services B.V. Page 5 of 11
3 Creating and updating conversion jobs 3.1 Create a new conversion job To create a new conversion job execute a HTTP request to the following URL: http://<edoc-host-url>/ converter/rest/jobs 3.1.1 Input parameters Name required default allowed values units description docurl yes string (valid url) URL to the input document for conversion doctype yes doc, docx, type of the input document xls, xlsx, ppt, pptx, pps, ppsx, rtf, txt, pdf, html, htm, dot, mht, mhtml, wri, wpd, wps, xl, odc, csv, pptm, pot, ppa, xml pingstart no string (valid url) URL to ping to when conversion starts pingdone no string (valid url) URL to ping to when conversion successfully ends pingerror no string (valid url) to ping to when conversion ends with error poly2bitmap no auto auto, on, off Turn the image optimization on, off or let the converter decide with the option auto. outputswf no true true, false create SWF output? imgformat no jpg jpg, png format for normal and zoomed images thumbformat no jpg jpg, png format for thumbnails jpgquality no 90 integer between 0 and 100 % JPEG quality for normal and zoom images (thumbnails are always 100) imgnormal no true true, false create normal size images? maximgwidth no 460 integer >= 100 pixels max allowed normal image width maximgheight no 620 integer >= 100 pixels max allowed normal image height imgzoom no true true, false create zoom images? outputpdf no true true, false include PDF doc and page files in output package? outputtxt no true true, false create TXT files for pages? outputtxtposition no true true, false create TXT position files for pages? thumbnaillist no list of {width,height} objects with values >= 10 3.1.2 Output pixels List of max allowed widths and heights for thumbnails. Format: {width:<integer>,height:<integer>}; {width:<integer>,height:<integer>}; When the conversion status is changes an http request will be executed to the appropriate ping page (pingstart, pingdone or pingerror) with a response header Location that contains the URL to the appropriate job: http://<edoc-host-url>/ converter/rest/jobs/<job_id> When the conversion is successful, a ZIP file with the resulting conversion files can be downloaded. See chapter 6 for more information. Copyright 2004-2010 Publitas Consulting Services B.V. Page 6 of 11
3.1.3 Example code <?php require_once "HTTP/Request.php"; // Create the request for conversion: $req =& new HTTP_Request("http://<edoc-host-url>/converter/rest/jobs"); $req->setbasicauth("username", "password"); $req->setmethod(http_request_method_post); $req->addheader('content-type', 'text/plain'); // Add all the needed parameters: $req->addpostdata("docurl", $req->addpostdata("doctype", $req->addpostdata("pingstart", $req->addpostdata("pingdone", $req->addpostdata("pingerror", "http://<your-domain>/issue.pdf"); "pdf"); "http://<your-domain>/test/pingstart"); "http://<your-domain>/test/pingdone"); "http://<your-domain>/test/pingerror"); // Conversion config options: $req->addpostdata("imgformat", "jpg"); $req->addpostdata("thumbformat", "jpg"); $req->addpostdata("jpgquality", "90"); $req->addpostdata("imgnormal", "true"); $req->addpostdata("maximgwidth", "460"); $req->addpostdata("maximgheight", "620"); $req->addpostdata("imgzoom", "true"); $req->addpostdata("outputpdf", "true"); $req->addpostdata("outputswf", "true"); $req->addpostdata("outputtxt", "true"); $req->addpostdata("outputtxtposition", "true"); $req->addpostdata("thumbnaillist", "{width:100,height:200};{width:150,height:300}"); // Send the request if (!PEAR::isError($req->sendRequest())) { //Location of the response contains job id echo $req->getresponseheader("location"); echo $req->getresponsebody(); // XML response }?> 3.2 Update existing conversion job To update an existing job execute a HTTP request to the following URL: http://<edoc-host-url>/ converter/rest/jobs 3.2.1 Input parameters The input parameters for updating a conversion job are the same as creating a new conversion job (see chapter 3.1.1). You only have to add the following parameter: Name required default allowed values units description conversionjobid no String if set, this parameter indicates the job to be updated; otherwise, a new job should be created 3.2.2 Output The output of updating a conversion job is the same as the output of creating a new conversion job. 3.2.3 Example code The code for updating a conversion job is the same as creating a new conversion job. Add the following line to determine the conversion job that you would like to update: $req->addpostdata("conversionjobid", "8abfb5021bb23383011bb233c16f0001"); Copyright 2004-2010 Publitas Consulting Services B.V. Page 7 of 11
4 Get information about a conversion job 4.1 Get conversion job details in JSON format You can get the JSON job details by the following GET method: http://<edoc-host-url>/converter/rest/jobs?conversionjobid=<job id>&format=json 4.1.1 Input parameters Name required default allowed values description conversionjobid no string if set, only one job will be returned (the one with the given ID) instead of the list status no CREATED, DOWNLOADING, if set, only the jobs with the specified status will be returned PENDING, STARTED, FINISHED, FAILED, CANCELED username no string if set, only jobs belonging to the stated user will be returned filterusername no string if set, only jobs belonging to users with usernames that contain filterusername as a substring will be returned deleted no true true, false if false, cleaned-up jobs will not be returned; if true, all jobs will be returned (both cleaned up and not cleaned-up) format no json json, xml specifies the format of the response 4.1.2 Output JSON {"jobsublist":[{"created":{"date":16,"day":2,"hours":21,"minutes":0,"month":8,"nanos":0,"seconds":56,"time ":1221591656000,"timezoneOffset":-120,"year":108},"deleted":false,"docType":"pdf","docUrl":"http://<yourdomain>/issue.pdf","id":"8abfb59b1c6c88f8011c6c895e110001","imgFormat":"jpg","imgNormal":true,"imgZo om":true,"jpgquality":90,"maximgheight":620,"maximgwidth":460,"outputpdf":true,"outputswf":true,"output Txt":true,"outputTxtPosition":true,"pingDone":"","pingError":"","pingStart":"","status":"CANCELED","thumbFor mat":"jpg","thumbnails":[],"username":"user"}],"totaljobsfiltered":1} Copyright 2004-2010 Publitas Consulting Services B.V. Page 8 of 11
4.2 Get conversion job details in XML format You can get the XML job details by the following GET method: http://<edoc-host-url>/converter/rest/jobs?conversionjobid=<job id>&format=xml 4.2.1 Input parameters The input parameters for getting the conversion job details in XML format are the same as the JSON format parameters (see chapter 4.1.1). You only have to change the parameter below. Name required default allowed values description format no json json, xml specifies the format of the response 4.2.2 Output XML <job> <jobsublist class="array"> <e class="object"> <created class="object"> <date type="number">16</date> <day type="number">2</day> <hours type="number">21</hours> <minutes type="number">0</minutes> <month type="number">8</month> <nanos type="number">0</nanos> <seconds type="number">56</seconds> <time type="number">1221591656000</time> <timezoneoffset type="number">-120</timezoneoffset> <year type="number">108</year> </created> <deleted type="boolean">false</deleted> <doctype type="string">pdf</doctype> <docurl type="string"> http://<your-domain>/issue.pdf </docurl> <id type="string">8abfb59b1c6c88f8011c6c895e110001</id> <imgformat type="string">jpg</imgformat> <imgnormal type="boolean">true</imgnormal> <imgzoom type="boolean">true</imgzoom> <jpgquality type="number">90</jpgquality> <maximgheight type="number">620</maximgheight> <maximgwidth type="number">460</maximgwidth> <outputpdf type="boolean">true</outputpdf> <outputswf type="boolean">true</outputswf> <outputtxt type="boolean">true</outputtxt> <outputtxtposition type="boolean">true</outputtxtposition> <pingdone type="string"/> <pingerror type="string"/> <pingstart type="string"/> <status type="string">canceled</status> <thumbformat type="string">jpg</thumbformat> <thumbnails class="array"/> <username type="string">user</username> </e> </jobsublist> <totaljobsfiltered type="number">1</totaljobsfiltered> </job> Copyright 2004-2010 Publitas Consulting Services B.V. Page 9 of 11
5 Canceling a conversion job To cancel a conversion job execute a HTTP request to the following URL: http://<edoc-host-url>/converter/rest/jobs/<job id> 5.1 Input parameters To cancel a conversion job it is required to set the HTTP request method. The request method has to be set to DELETE by setting the following line: $req->setmethod(http_request_method_delete); 5.2 Example code <?php require_once "HTTP/Request.php"; // Create the request for conversion: //Use location received from post job here: $req =& new HTTP_Request("http://<edoc-host-url>/converter/rest/jobs/<job id>"); // Authenticate via your API username/password: $req->setbasicauth("username", "password"); // It's a POST request: $req->setmethod(http_request_method_delete); // Send the request if (!PEAR::isError($req->sendRequest())) { // XML response echo $req->getresponsebody(); }?> Copyright 2004-2010 Publitas Consulting Services B.V. Page 10 of 11
6 Downloading conversion job results After the conversion job is finished a ZIP file with the resulting conversion files can be downloaded. This can be downloaded with the following URL: http://<edoc-host-url>/converter/download/<job id> Copyright 2004-2010 Publitas Consulting Services B.V. Page 11 of 11