Access the BuildVu Microservice using cURL

Table of contents

1. Introduction
2. Prerequisites
3. Code Example
4. Return result to a callback url
5. Configuration Options
6. Upload by URL
7. Using Authentication
8. Further details

Introduction

The following tutorial shows you how to convert PDF files to HTML or SVG using a hosted BuildVu cloud API, such as:

• the IDRsolutions trial and cloud subscription service
• your own self-hosted BuildVu microservice

Whilst the above services can be accessed with cURL using the REST API.

Prerequisites

Before you begin you will need to ensure cURL is installed. The set up varies based on your operating system, more details can be found on the curl website.

Code Example

Here is a basic code example to convert PDF files to HTML or SVG.
Please note the file entry must be ‘@’ followed by the path (absolute or relative) to the file.
Configuration options and advanced features can be found below.

curl -X POST -F input="upload" -F file="@/path/to/file/myfile.pdf" https://cloud.idrsolutions.com/cloud/buildvu
# Variable token required when connecting to the IDRsolutions trial or cloud subscription servers, example below
curl -X POST -F input="upload" -F file="@/path/to/file/myfile.pdf" -F token=Token https://cloud.idrsolutions.com/cloud/buildvu

The response will be in JSON format containing a uuid.

 {"uuid" : "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"}

You can use to poll the progress of your conversion and retrieve the URL for the output once the conversion is complete.

curl https://cloud.idrsolutions.com/cloud/buildvu?uuid=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa

The response will be in JSON format and provided the following details.

 {
     "state" : "processed", 
     "downloadUrl" : "output/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/myfile.zip",
     "previewUrl" : "output/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/myfile/index.html"
 }

You can use the previewURL to preview the output in your browser.

You may also download the converted output using the download URL. This can be done with the following cURL request.

# Download the file to the current directory as it is named, in this case "myfile.zip"
curl https://cloud.idrsolutions.com/cloud/buildvu/output/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/myfile.zip -LO --output "output.zip"

Return result to a callback url

The BuildVu Microservice accepts a callback url to send the status of a conversion on completion. Using a callback url removes the need to poll the service to determine when the conversion is complete.
The callback url can be provided as shown below.

curl -X POST -F input="upload" -F callbackUrl="http://listener.url" -F file="@/path/to/file/myfile.pdf" https://cloud.idrsolutions.com/cloud/buildvu
# Variable token required when connecting to the IDRsolutions trial or cloud subscription servers, example below
curl -X POST -F input="upload" -F callbackUrl="http://listener.url" -F file="@/path/to/file/myfile.pdf" -F token=Token https://cloud.idrsolutions.com/cloud/buildvu

Configuration Options

The BuildVu API accepts a stringified JSON object containing key value pair configuration options to customise your conversion. The settings should be added before the URL in the cURL command. A full list of the configuration options to convert PDF files to HTML or SVG can be found here.

Note that the syntax for escaping double quotes can vary depending on the environment you use, make sure to check what works for your specific environment:

Note that for PowerShell your command should start with curl.exe --% to avoid parsing errors.

Upload by URL

As well as uploading a local file you can also provide a URL which the BuildVu Microservice will download and then perform the conversion. To do this you should replace the input and file values with the following.

-F input=download -F url="http://exampleURL/exampleFile.pdf"

Using Authentication

If you have deployed your own BuildVu Microservice that requires a username and password to convert PDF files to HTML or SVG, you will need to provide them with each conversion. These are provided by adding the user flag with a username and password before the URL.

--user username:password

Further details

Official cURL website
BuildVu Microservice API
BuildVu Microservice Use