oxidize-pdf-api

REST API for oxidizePdf - A high-performance PDF manipulation library written in Rust.

Features

• RESTful API: Clean and intuitive HTTP endpoints for PDF operations
• Async Processing: Built on Tokio for high-performance async I/O
• File Upload Support: Multipart form data handling for PDF uploads
• CORS Support: Cross-origin resource sharing for web applications
• Community Edition: Full-featured API for common PDF operations

Installation

From Source

git clone https://github.com/yourusername/oxidize-pdf
cd oxidize-pdf/oxidize-pdf-api
cargo build --release

Using Cargo

cargo install oxidize-pdf-api

Running the Server

# Default port 3000
oxidize-pdf-api

# Custom port
oxidize-pdf-api --port 8080

# With environment variables
OXIDIZEPDF_API_PORT=8080 RUST_LOG=info oxidize-pdf-api

API Endpoints

Health Check

GET /health

Returns server status and version information.

Merge PDFs

POST /api/merge
Content-Type: multipart/form-data

Merge multiple PDF files into a single document.

Request:

• files: Multiple PDF files (form field name: file)
• preserve_metadata: Boolean (optional, default: true)
• optimize: Boolean (optional, default: false)

Response:

{
  "success": true,
  "pages": 42,
  "size": 1048576,
  "processing_time_ms": 150
}

Returns the merged PDF file with appropriate headers.

Split PDF

POST /api/split
Content-Type: multipart/form-data

Split a PDF into individual pages or chunks.

Request:

• file: PDF file to split
• mode: "pages" | "chunks" (optional, default: "pages")
• chunk_size: Number (optional, for chunks mode)

Response: ZIP file containing split PDFs

Extract Pages

POST /api/extract
Content-Type: multipart/form-data

Extract specific pages from a PDF.

Request:

• file: Source PDF file
• pages: Page range (e.g., "1-5,10,15-20")

Response: PDF containing only the specified pages

Rotate Pages

POST /api/rotate
Content-Type: multipart/form-data

Rotate pages in a PDF.

Request:

• file: PDF file
• angle: 90 | 180 | 270
• pages: Page range (optional, rotates all if not specified)

Response: PDF with rotated pages

Extract Text

POST /api/text
Content-Type: multipart/form-data

Extract text content from a PDF.

Request:

• file: PDF file
• pages: Page range (optional)
• format: "plain" | "json" (optional, default: "plain")

Response:

• Plain text or JSON structure with page-by-page text

Get PDF Info

POST /api/info
Content-Type: multipart/form-data

Get metadata and information about a PDF.

Request:

• file: PDF file

Response:

{
  "pages": 10,
  "title": "Document Title",
  "author": "Author Name",
  "subject": "Document Subject",
  "keywords": "pdf, document",
  "creator": "oxidize_pdf",
  "producer": "oxidize_pdf v0.1.0",
  "creation_date": "2024-01-01T12:00:00Z",
  "modification_date": "2024-01-15T14:30:00Z",
  "file_size": 1048576,
  "pdf_version": "1.7"
}

Example Usage

cURL

# Merge PDFs
curl -X POST http://localhost:3000/api/merge \
  -F "file=@doc1.pdf" \
  -F "file=@doc2.pdf" \
  -F "file=@doc3.pdf" \
  -o merged.pdf

# Extract pages
curl -X POST http://localhost:3000/api/extract \
  -F "file=@input.pdf" \
  -F "pages=1-5,10" \
  -o extracted.pdf

# Get PDF info
curl -X POST http://localhost:3000/api/info \
  -F "file=@document.pdf"

JavaScript/Fetch

// Merge PDFs
const formData = new FormData();
formData.append('file', file1);
formData.append('file', file2);
formData.append('preserve_metadata', 'true');

const response = await fetch('http://localhost:3000/api/merge', {
  method: 'POST',
  body: formData
});

const blob = await response.blob();
// Handle the merged PDF blob

Python

import requests

# Merge PDFs
files = [
    ('file', open('doc1.pdf', 'rb')),
    ('file', open('doc2.pdf', 'rb'))
]

response = requests.post(
    'http://localhost:3000/api/merge',
    files=files
)

with open('merged.pdf', 'wb') as f:
    f.write(response.content)

Configuration

Environment variables:

• OXIDIZEPDF_API_PORT: Server port (default: 3000)
• OXIDIZEPDF_API_HOST: Server host (default: 0.0.0.0)
• OXIDIZEPDF_MAX_FILE_SIZE: Maximum upload size in bytes (default: 100MB)
• RUST_LOG: Logging level (trace, debug, info, warn, error)

Error Handling

All endpoints return consistent error responses:

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": "Additional error details"
}

HTTP status codes:

• 200: Success
• 400: Bad Request (invalid input)
• 413: Payload Too Large
• 415: Unsupported Media Type
• 500: Internal Server Error

Security

• File size limits to prevent DoS
• Input validation for all parameters
• Temporary file cleanup after processing
• CORS configuration for web security

License

This project is licensed under the MIT License - see the LICENSE file for details.

See Also

• oxidize-pdf - Core PDF library
• oxidize-pdf-cli - CLI tool
• API Documentation - Detailed API docs