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 Toolkit Cloud.
- 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 Cloud API Reference Guide .