Pdfcrowd Blog

Product updates, tips & tricks

Pdfcrowd API v2 migration guide

Overview

The Pdfcrowd API v2 is the new generation of our API. It is not 100% backward compatible but the changes are mostly syntactic and the migration from API v1 should be straightforward.

If you want to switch your current API v1 plan to API v2, please follow these steps:

  1. Activate the free API v2 trial in your account page.
  2. Follow the instructions below and migrate your API v1 implementation to API v2.
  3. If the API v2 works to your satisfaction, choose from our API v2 plans.
  4. If you no longer need the API v1 implementation, you can cancel the API v1 plan.

API client libraries

If you use our API client library, install the latest version from the API home page. The library supports both API versions and you can easily run both implementations side by side under your current Pdfcrowd account.

The migration should consist of these steps:

  1. Instantiate the API v2 client.
  2. Migrate the convert*** method (the one that returns PDF).
  3. Migrate the conversion settings.
  4. Error handling (important)

API client instantiation

The code below shows how to instantiate API clients. The first line corresponds to what you have in your current API v1 implementation (client_v1). The second line shows how to instantiate the API v2 client (client_v2).

// PHP
client_v1 = new Pdfcrowd("username", "apikey")
client_v2 = new \Pdfcrowd\HtmlToPdfClient("username", "apikey")
// Java
Client client_v1 = new Client("username", "apikey");
Pdfcrowd.HtmlToPdfClient client_v2 = new Pdfcrowd.HtmlToPdfClient("username", "apikey");
// .NET
pdfcrowd.Client client_v1 = new pdfcrowd.Client("username", "apikey");
pdfcrowd.HtmlToPdfClient client_v2 = new pdfcrowd.HtmlToPdfClient("username", "apikey");
# Ruby
client_v1 = Pdfcrowd::Client.new("username", "apikey");
client_v2 = Pdfcrowd::HtmlToPdfClient.new("username", "apikey");
# Python
client_v1 = pdfcrowd.Client("username", "apikey")
client_v2 = pdfcrowd.HtmlToPdfClient("username", "apikey")
// Node.js
var client_v1 = new pdf.Pdfcrowd("username", "apikey")
var client_v2 = new pdfcrowd.HtmlToPdfClient("username", "apikey")

Conversion methods

The following table shows the mapping of conversion methods.

API v1 Target API v2
convertURI file convertUrlToFile
variable convertUrl
stream convertUrlToStream
convertFile file convertFileToFile
variable convertFile
stream convertFileToStream
convertHtml file convertStringToFile
variable convertString
stream convertStringToStream

Conversion settings methods

If your API implementation is in Node.js, continue below.

If your API v1 implementation customizes the conversion settings, check the following table to find the corresponding API v2 functionality.

API v1 API v2 Details
setPageWidth setPageWidth see Units
setPageHeight setPageHeight see Units
setPageMargins setPageMargins see Units
setHorizontalMargin setMarginTop
setMarginBottom
or
setPageMargins
see Units
setVerticalMargin setMarginLeft
setMarginRight
or
setPageMargins
see Units
setFooterHtml setFooterHtml see Header and footer variables
setFooterUrl setFooterUrl see Header and footer variables
setHeaderHtml setHeaderHtml see Header and footer variables
setHeaderUrl setHeaderUrl see Header and footer variables
setHeaderFooterPageExcludeList setExcludeHeaderOnPages
setExcludeFooterOnPages
setPageNumberingOffset setPageNumberingOffset
enableImages setDisableImageLoading invert the argument value
enableBackgrounds setNoBackground invert the argument value
enableJavaScript setDisableJavascript invert the argument value
setDefaultTextEncoding setDefaultEncoding API v1 defaults to "utf-8", API v2 tries to auto-detect the encoding
usePrintMedia setUsePrintMedia
setEncrypted setEncrypt
setUserPassword setUserPassword
setOwnerPassword setOwnerPassword
setNoPrint setNoPrint
setNoModify setNoModify
setNoCopy setNoCopy
setPageLayout setPageLayout use "single-page" instead CONTINUOUS; CONTINUOUS and CONTINUOUS_FACING are not supported in API v2
setPageMode setPageMode use "full-screen" instead FULLSCREEN
setInitialPdfZoomType setInitialZoomType values mapping:
FIT_WIDTH ⇒ "fit-width"
FIT_HEIGHT ⇒ "fit-height"
FIT_PAGE ⇒ "fit-page"
setInitialPdfExactZoom setInitialZoom
setPdfScalingFactor setScaleFactor multiply value by 100 for API v2
setAuthor setAuthor
setWatermark setPageWatermark
setMultipageWatermark
API v1 uses a raster image, API v2 uses a PDF file
setWatermarkInBackground setPageBackground
setMultipageBackground
API v1 uses a raster image, API v2 uses a PDF file
useSSL setUseHttp invert the argument value
numTokens getRemainingCreditCount numTokens method returns the credit count always, getRemainingCreditCount returns the credit count after a successful conversion only
setMaxPages setPrintPageRange API v2 allows a range, so use "-N" for the first N pages
setFailOnNon200 setFailOnMainUrlError
setFailOnAnyUrlError

Node.js

API client instantiation:

// Node.js
var client_v1 = new pdf.Pdfcrowd("username", "apikey")
var client_v2 = new pdfcrowd.HtmlToPdfClient("username", "apikey")

The API v1 client uses a dictionary of options. API v2 uses methods on the client object.

// API v1
client_v1.convertURI(
    'http://example.com',
    pdf.saveToFile("example.pdf"), {
        width: "11in",
        height: "8.5in",
        user_print_media: true,
    }
);

// API v2
client_v2.setPageSize("Letter");
client_v2.setUsePrintMedia(true);

client_v2.convertUrlToFile(
    "http://example.com",
    "example.pdf",
    function(err, fileName) {
        if (err) return console.error("Pdfcrowd Error: " + err);
        // success, pdf was saved to fileName
    });

See the HTML to PDF API v2 - Node.js documentation for more examples.

The following table maps API v1 options to API v2 methods. The mapping of the convert*** methods is here.

API v1 API v2 Details
width setPageWidth see Units
height setPageHeight see Units
margin_top setMarginTop see Units
margin_right setMarginRight see Units
margin_bottom setMarginBottom see Units
margin_left setMarginLeft see Units
hmargin setMarginTop
setMarginBottom
see Units
vmargin setMarginLeft
setMarginRight
see Units
footer_html setFooterHtml see Header and footer variables
footer_url setFooterUrl see Header and footer variables
header_html setHeaderHtml see Header and footer variables
header_url setHeaderUrl see Header and footer variables
header_footer_page_exclude_list setExcludeHeaderOnPages
setExcludeFooterOnPages
page_numbering_offset setPageNumberingOffset
no_images setDisableImageLoading
no_backgrounds setNoBackground
no_javascript setDisableJavascript
text_encoding setDefaultEncoding API v1 default is "utf-8", API v2 default is auto detect
use_print_media setUsePrintMedia
encrypted setEncrypt
author setAuthor
user_pwd setUserPassword
owner_pwd setOwnerPassword
no_print setNoPrint
no_modify setNoModify
no_copy setNoCopy
page_layout setPageLayout use "single-page" instead 1; 2 and 3 are not supported in API v2
initial_pdf_zoom_type setInitialZoomType values mapping:
1 ⇒ "fit-width"
2 ⇒ "fit-height"
3 ⇒ "fit-page"
4 is not supported
initial_pdf_zoom setInitialZoom
page_mode setPageMode values mapping:
1 is not supported
2 ⇒ "thumbnails"
3 ⇒ "full-screen"
max_pages setPrintPageRange API v2 allows a range, so use "-N" for the first N pages
pdf_scaling_factor setScaleFactor multiply value by 100 for API v2
watermark_url setPageWatermark
setMultipageWatermark
API v1 uses a raster image, API v2 uses a PDF file
watermark_in_background setPageBackground
setMultipageBackground
API v1 uses a raster image, API v2 uses a PDF file
fail_on_non200 setFailOnMainUrlError
setFailOnAnyUrlError

HTTP access

The API v2 endpoint is https://api.pdfcrowd.com/convert/
The authentication method for user credentials is HTTP Basic Access Authentication.

Convert URL

# API v1
curl -F "username=username" -F "key=apikey" \
     -F 'src=http://example.com' \
     -o example.pdf \
     https://pdfcrowd.com/api/pdf/convert/uri/

# API v2
curl -f -u "username:apikey" \
     -F "url=http://www.example.com" \
     -o example.pdf \
     https://api.pdfcrowd.com/convert/

Convert file

# API v1
curl -F "username=username" -F "key=apikey" \
     -F 'src=@example.html' \
     -o example.pdf \
      https://pdfcrowd.com/api/pdf/convert/html/

# API v2
curl -f -u "username:apikey" \
     -F "file=@example.html" \
     -o example.pdf \
     https://api.pdfcrowd.com/convert/

Convert string

# API v1
curl -F "username=username" -F "key=apikey" \
     -F "src=<html><body><h1>Hello World!</h1></body></html>" \
     -o hello.pdf \
     https://pdfcrowd.com/api/pdf/convert/html/

# API v2
curl -f -u "username:apikey" \
     -F "text=<html><body><h1>Hello World!</h1></body></html>" \
     -o hello.pdf \
     https://api.pdfcrowd.com/convert/

The following table maps API v1 options to API v2 options.

API v1 API v2 Details
width page_width see Units
height page_height see Units
margin_top margin_top see Units
margin_right margin_right see Units
margin_bottom margin_bottom see Units
margin_left margin_left see Units
hmargin margin_top
margin_bottom
see Units
vmargin margin_left
margin_right
see Units
footer_html footer_html see Header and footer variables
footer_url footer_url see Header and footer variables
header_html header_html see Header and footer variables
header_url header_url see Header and footer variables
header_footer_page_exclude_list exclude_header_on_pages
exclude_footer_on_pages
page_numbering_offset page_numbering_offset
no_images disable_image_loading
no_backgrounds no_background
no_javascript disable_javascript
text_encoding default_encoding API v1 defaults to "utf-8", API v2 tries to auto-detect the encoding
use_print_media use_print_media
encrypted encrypt
author author
user_pwd user_password
owner_pwd owner_password
no_print no_print
no_modify no_modify
no_copy no_copy
page_layout page_layout use "single-page" instead 1; 2 and 3 are not supported in API v2
initial_pdf_zoom_type initial_zoom_type values mapping:
1 ⇒ "fit-width"
2 ⇒ "fit-height"
3 ⇒ "fit-page"
4 is not supported
initial_pdf_zoom initial_zoom
page_mode page_mode values mapping:
1 is not supported
2 ⇒ "thumbnails"
3 ⇒ "full-screen"
max_pages print_page_range API v2 allows a range, so use "-N" for the first N pages
pdf_name output_name
pdf_scaling_factor scale_factor multiply value by 100 for API v2
watermark_url page_watermark
multipage_watermark
API v1 uses a raster image, API v2 uses a PDF file
watermark_in_background page_background
multipage_background
API v1 uses a raster image, API v2 uses a PDF file
fail_on_non200 fail_on_main_url_error
fail_on_any_url_error
content_disposition content_disposition

Miscellaneous

Variables
Replace variables with HTML classes:
%u ⇒ pdfcrowd-source-url
%p ⇒ pdfcrowd-page-number
%n ⇒ pdfcrowd-page-count

<!-- API v1 -->
Page %p of %n.

<!-- API v2 -->
Page <span class='pdfcrowd-page-number'></span> of <span class='pdfcrowd-page-count'></span>.

Placement
API v1 places headers and footers to the margin area. API v2 places them to the printing area. The height of the header and footer can be set with setHeaderHeight and setFooterHeight.

Units

API v1 allows to specify a unit-less numeric value that is interpreted as points (1/72 of an inch). API v2 doesn't allow this, the value must be specified with a mm, in, cm or pt suffix.

Addendum