Usage as a Web Service

From version 2.1 the JODConverter webapp includes a very simple “web service”, meaning a way of invoking the converter service programmatically from a remote client written in any language using HTTP.

It’s not a full fledged “web service” involving SOAP or anything like that, in fact is is purely based on the HTTP protocol without any XML at all. It just serves the purpose with the minimum amount of complexity.

Assuming you installed the web application as described in the previous page, the service will be available locally at the following URL

http://localhost:8080/converter/service

To get back a document converted in your desired format, all you have to do is send an HTTP request as follows

1. use the POST method and send the input document data as the request body
2. specify the correct input document type as the Content-Type header
3. specify the desired output document type as the Accept header

So the simplest request to convert from a TXT document into PDF will be something like the following

 POST /converter/service HTTP/1.1
 Host: localhost
 Content-Type: text/plain
 Accept: application/pdf
 
 Hello world!

and the response body will contain the PDF document.

PHP sample client

A simple client written in PHP to convert a document from ODT to PDF could be

<?php
require_once 'HTTP/Request.php';

class DocumentConverterClient {

    var $url = "http://localhost:8080/converter/service";

    function convert($inputData, $inputType, $outputType) {
        $request = new HTTP_Request($this->url);
        $request->setMethod("POST");
        $request->addHeader("Content-Type", $inputType);
        $request->addHeader("Accept", $outputType);
        $request->setBody($inputData);
        $request->sendRequest();
        return $request->getResponseBody();
    }
}

$documentConverter = new DocumentConverterClient();

$inputFile = "document.odt";
$inputType = "application/vnd.oasis.opendocument.text";
$outputFile = "document.pdf";
$outputType = ""application/pdf";

$outputData = $documentConverter->convert(file_get_contents($inputFile), $inputType, $outputType);
file_put_contents($outputFile, $outputData);

?>

(this example requires the PEAR HTTP Request module.)

C#.NET sample client

Here’s the same example but written in C# for the .NET framework

using System;
using System.IO;
using System.Net;

namespace DocumentConverterClient
{
    class MainClass
    {
        public static void Main(string[] args)
        {
            string url = "http://localhost:8080/converter/service";
			
            string inputFile = "document.odt";
            string outputFile = "document.pdf";
		
            WebClient webClient = new WebClient();
            webClient.Headers.Set("Content-Type", "application/vnd.oasis.opendocument.text");
            webClient.Headers.Set("Accept", "application/pdf");
            FileStream inputStream = File.OpenRead(inputFile);
            BinaryReader reader = new BinaryReader(inputStream);
            byte[] inputData = reader.ReadBytes((int) inputStream.Length);
            reader.Close();
			
            byte[] outputData = webClient.UploadData(url, "POST", inputData);		
			
            FileStream outputStream = File.Create(outputFile);
            BinaryWriter writer = new BinaryWriter(outputStream);
            writer.Write(outputData);
            writer.Close();
        }
    }
}

Unix command line example

It’s also trivially easy to invoke the service from a Unix command line using wget

$ wget http://localhost:8080/converter/service \
    --post-file=document.odt \
    --header="Content-Type: application/vnd.oasis.opendocument.text" \
    --header="Accept: application/pdf" \
    --output-document=document.pdf

(Apparently this example only works with wget version 1.10 or higher; prior versions don’t allow to override the Content-Type.)

Other languages

It’s very easy to write a client in any language as long as it provides some support for HTTP (which one doesn’t these days?). This includes Python, Perl, Ruby, .NET… and Java of course. Contributions are welcome!