Upload a Single Binary File to pdfRest with Java

Share this page

Learn how to upload a single binary file to pdfRest with Java and the Upload Files API Tool. The code sends raw file bytes to /upload, provides the filename in a header, and reads the new resource ID. We'll move from input and authentication setup through the request and returned data involved when you upload a single binary file to pdfRest.

Why Upload a Single Binary File to pdfRest with Java?

A multi-step application may want to transfer a source once and reference it by ID in later operations. Uploading first separates file transfer from the processing request and avoids repeated uploads.

The Java example sends the file bytes directly to /upload and supplies the filename in the Content-Filename header. Binary upload mode does not wrap the file in multipart form data.

Java Code Example

import io.github.cdimascio.dotenv.Dotenv;
import java.io.File;
import java.io.IOException;
import okhttp3.*;
import org.json.JSONObject;

public class Upload {

  // By default, we use the US-based API service. This is the primary endpoint for global use.
  private static final String API_URL = "https://api.pdfrest.com";

  // For GDPR compliance and enhanced performance for European users, you can switch to the EU-based
  // service by commenting out the URL above and uncommenting the URL below.
  // For more information visit https://pdfrest.com/pricing#how-do-eu-gdpr-api-calls-work
  // private static final String API_URL = "https://eu-api.pdfrest.com";

  // Specify the path to your file here, or as the first argument when running the program.
  private static final String DEFAULT_FILE_PATH = "/path/to/file.pdf";

  // Specify your API key here, or in the environment variable PDFREST_API_KEY.
  // You can also put the environment variable in a .env file.
  private static final String DEFAULT_API_KEY = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

  public static void main(String[] args) {
    File inputFile;
    if (args.length > 0) {
      inputFile = new File(args[0]);
    } else {
      inputFile = new File(DEFAULT_FILE_PATH);
    }

    final Dotenv dotenv = Dotenv.configure().ignoreIfMalformed().ignoreIfMissing().load();

    final RequestBody requestBody =
        RequestBody.create(inputFile, MediaType.parse("application/pdf"));

    Request request =
        new Request.Builder()
            .header("Api-Key", dotenv.get("PDFREST_API_KEY", DEFAULT_API_KEY))
            .header("Content-Filename", "File.pdf")
            .url(API_URL + "/upload")
            .post(requestBody)
            .build();
    try {
      OkHttpClient client = new OkHttpClient().newBuilder().build();
      Response response = client.newCall(request).execute();
      System.out.println("Result code " + response.code());
      if (response.body() != null) {
        System.out.println(prettyJson(response.body().string()));
      }
    } catch (IOException e) {
      throw new RuntimeException(e);
    }
  }

  private static String prettyJson(String json) {
    // https://stackoverflow.com/a/9583835/11996393
    return new JSONObject(json).toString(4);
  }
}

Source: Java sample on GitHub.

Breaking Down the Code

Load the Java HTTP and JSON dependencies

import io.github.cdimascio.dotenv.Dotenv;
import java.io.File;
import java.io.IOException;
import okhttp3.*;
import org.json.JSONObject;

The Java setup assigns a clear role to each library: HTTP communication, credential lookup, or JSON handling.

Choose the input and load credentials

// service by commenting out the URL above and uncommenting the URL below.
  // For more information visit https://pdfrest.com/pricing#how-do-eu-gdpr-api-calls-work
  // private static final String API_URL = "https://eu-api.pdfrest.com";

  // Specify the path to your file here, or as the first argument when running the program.
  private static final String DEFAULT_FILE_PATH = "/path/to/file.pdf";

  // Specify your API key here, or in the environment variable PDFREST_API_KEY.
  // You can also put the environment variable in a .env file.
  private static final String DEFAULT_API_KEY = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

  public static void main(String[] args) {
    File inputFile;
    if (args.length > 0) {
      inputFile = new File(args[0]);
    } else {
      inputFile = new File(DEFAULT_FILE_PATH);
    }

    final Dotenv dotenv = Dotenv.configure().ignoreIfMalformed().ignoreIfMissing().load();

    final RequestBody requestBody =

The input setup keeps a visible default path, accepts an override from the command line, and reads the API key through dotenv.

Build the binary request body

final RequestBody requestBody =
        RequestBody.create(inputFile, MediaType.parse("application/pdf"));

    Request request =
        new Request.Builder()
            .header("Api-Key", dotenv.get("PDFREST_API_KEY", DEFAULT_API_KEY))
            .header("Content-Filename", "File.pdf")
            .url(API_URL + "/upload")
            .post(requestBody)
            .build();
    try {

The file becomes the HTTP request body itself, and Content-Filename tells pdfRest what name to assign the uploaded resource. OkHttp derives Content-Type from the media type supplied to RequestBody.create.

Send the request to pdfRest

Request request =
        new Request.Builder()
            .header("Api-Key", dotenv.get("PDFREST_API_KEY", DEFAULT_API_KEY))
            .header("Content-Filename", "File.pdf")
            .url(API_URL + "/upload")
            .post(requestBody)
            .build();
    try {
      OkHttpClient client = new OkHttpClient().newBuilder().build();
      Response response = client.newCall(request).execute();
      System.out.println("Result code " + response.code());

This POST request posts the multipart content to pdfRest and keeps deployment-region changes independent of the rest of the Java code.

Read the API response

.build();
    try {
      OkHttpClient client = new OkHttpClient().newBuilder().build();
      Response response = client.newCall(request).execute();
      System.out.println("Result code " + response.code());
      if (response.body() != null) {
        System.out.println(prettyJson(response.body().string()));
      }
    } catch (IOException e) {
      throw new RuntimeException(e);
    }
  }

  private static String prettyJson(String json) {
    // https://stackoverflow.com/a/9583835/11996393
    return new JSONObject(json).toString(4);

A successful upload returns a files array containing the new resource ID and file details, which can be retained for a later API request.

Beyond the Tutorial

Together, we stepped through the Java request needed to upload a single binary file to pdfRest. With that foundation, resource IDs can be reused by compatible API Tools until deletion or the configured retention period removes the file.

As you build this into a larger workflow, set Content-Filename to a meaningful name because later operations use resource metadata as well as the stored bytes. Retain the returned ID only as long as the workflow needs it, then delete the resource explicitly or allow the configured retention policy to expire it.

Try the Upload a Single Binary to pdfRest operation with representative files in API Lab. Review the Upload Files API Tool documentation for supported values and production considerations.

How to Upload a Single Binary File to pdfRest with Java