Api Polling

Introduction

API Polling is a technique used to repeatedly check the status of a long-running process by making periodic requests to a specific endpoint. In pdfRest, the /request-status endpoint is designed for this purpose. This guide will walk you through the steps to implement and use API Polling effectively.

Prerequisites

Before you start, ensure you have:

  • Access to the pdfRest API.
  • An API key for authentication.
  • Basic knowledge of HTTP requests and responses.

Step-by-Step Guide

1. Making the Initial Request

When you initiate a process (e.g., converting a document), you will make an initial request to the relevant endpoint. This request will return a unique ID that you will use for polling.

Example Initial Request:

curl -X POST "https://api.pdfrest.com/convert" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "source": "https://example.com/document.pdf",
           "format": "docx"
         }'

Response:

{
  "id": "12345",
  "status": "processing"
}

2. Polling the /request-status Endpoint

Using the ID from the initial request, you will poll the /request-status endpoint to check the status of your request.

Polling Request:

curl -X GET "https://api.pdfrest.com/request-status/12345" \
     -H "Authorization: Bearer YOUR_API_KEY"

3. Understanding Status Codes

The server will respond with different status codes indicating the state of your request:

  • 202 Accepted: The request is still being processed.
  • 200 OK: The request has been completed successfully.
  • 4xx: There was an error with your request.

Example Response:

{
  "id": "12345",
  "status": "completed",
  "result": "https://example.com/converted-document.docx"
}

4. Handling the Final Data

Once the request is completed (200 OK), you can retrieve the final data from the provided URL in the response.

Example Final Data Retrieval:

curl -X GET "https://example.com/converted-document.docx"

Best Practices

  • Polling Interval: Choose an appropriate polling interval (e.g., every 5 seconds) to avoid excessive requests that may lead to rate limiting.
  • Error Handling: Implement robust error handling to manage different status codes and potential issues.
  • Timeouts: Set reasonable timeouts for your polling requests to prevent indefinite waiting.

Conclusion

API Polling is a powerful technique for managing long-running processes in pdfRest. By following this guide, you can effectively implement and use the /request-status endpoint to monitor and retrieve the status of your requests.

For more detailed information, refer to the pdfRest API Reference Guide.

Acknowledgements
Acknowledgements for pdfRest API service.
Compress PDF Custom Profiles