How to Poll for API Request Status with cURL, Tutorial

Share this page

Why Use API Polling with cURL?

The pdfRest API Polling Tool offers a powerful solution for developers working with cURL and asynchronous pdfRest functionalities. cURL, a popular command-line tool, excels at making API calls. However, when dealing with complex tasks, requests can take longer to complete, which can result in timeouts, depending on your tools and implementation.

Imagine you're building a script that compresses a batch of large PDFs. Traditionally, you'd use cURL to send each conversion request and wait for each response to be returned before moving on. With API Polling enabled, the response immediately returns a unique requestID. Your script can then move on to other tasks while the conversion runs in the background. Later, when your script is ready, it can use cURL to send a separate request to the /request-status endpoint with the requestID This provides a real-time update on the compression's status. Based on the response, your script can then initiate the next step, such as downloading the compressed document. This approach allows your script to work efficiently, avoiding unnecessary waiting and streamlining the overall process.

API Polling with cURL Code Example

Enable API Polling with Processing Step

curl -X POST "https://api.pdfrest.com/pdf" \
  -H "Accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "Response-Type: requestId" \
  -H "Api-Key: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -F "file=@/path/to/file"

Poll for Status of Processing Request

curl -X GET "https://api.pdfrest.com/request-status/xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
    -H "Api-Key: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Breaking Down the POST Request Code

The cURL commands provided above are structured to communicate with the pdfRest API to send a processing request with API Polling enabled and then to poll the status of the request. Here's a breakdown of each part of the initial POST request:

curl -X POST "curl -X POST "https://api.pdfrest.com/pdf"

This initializes a cURL request using the POST method to the specified URL, which is the endpoint for converting files to PDF - an example we use here to illustrate how to enable API Polling. Note that API Polling can be enabled for any endpoint.

-H "Accept: application/json"

This header tells the server that the client expects a response in JSON format.

-H "Content-Type: multipart/form-data"

This header indicates that the data being sent is in multipart/form-data format, which is necessary for uploading files.

-H "Response-Type: requestId"

This is the important header parameter we are adding to the POST request that enables API Polling. This tells pdfRest to immediately return a requestId instead of waiting for the processing to complete and returning the full response at that time. The requestId will be used to poll for the response status instead.

-H "Api-Key: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

The Api-Key header is used for authentication. Replace the placeholder with your actual API key provided by pdfRest.

-F "file=@/path/to/file"

The -F flag is used to specify each file being uploaded. The '@' symbol is followed by the file path, which tells cURL to get the file content from the specified location. Repeat this flag for each file you wish to upload.

Instead of returning a full JSON response after processing finishes, this will immediately return a JSON response with a single requestId, like:

{
   "requestId": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Breaking Down the GET Request Code

Here's a breakdown of each part of the GET request to poll for the status to the previous POST request:

curl -X GET "https://api.pdfrest.com/request-status/xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

This initializes a cURL request using the GET method to the specified URL, which is the endpoint for polling request statuses. Replace the placeholder with your actual requestID returned from the processing step.

-H "Api-Key: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

An Api-Key header is also required to use API Polling - replace with your actual key.

If the request has not yet completed, the response will look like this:

{
   "status": "pending",
   "requestId": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

If the request has completed, the response will look like this:

{
   "status": "completed",
   "requestId": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "outputUrl": "https://api.pdfrest.com/resource/01240b25a-8936-4437-8652-8410130f1199?format=file",
   "outputId": "01240b25a-8936-4437-8652-8410130f1199",
   "inputId": "112f7ea0d-0e56-44bc-a3d2-42fdff96d993"
}

Beyond the Tutorial

By following the above steps, you have learned how to use cURL to enable API Polling with your processing requests and poll for the status of the request. This offers flexibility in the design of your workflow and helps to prevent timeouts for longer-running processes. To explore and demo all of the pdfRest API Tools, visit the API Lab. For a comprehensive understanding of the available endpoints and their functionalities, refer to the API Reference Guide.

Note: This is an example of a multipart API call. Code samples using JSON payloads can be found at GitHub.