Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
725 lines (562 loc) · 12.1 KB

API_DOCUMENTATION.md

File metadata and controls

725 lines (562 loc) · 12.1 KB

PDF Editor API Documentation

Complete API reference for the PDF Editor application.

Base URL

http://localhost:5000/api

Authentication

Most endpoints support optional JWT authentication. Include the token in the Authorization header:

Authorization: Bearer <your_jwt_token>

Authentication Endpoints

Register User

POST /api/auth/register

Register a new user account.

Request Body:

{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "securepassword123"
}

Response (201):

{
  "message": "User registered successfully",
  "user": {
    "id": "uuid",
    "username": "johndoe",
    "email": "john@example.com",
    "created_at": "2024-01-01T00:00:00"
  },
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Login

POST /api/auth/login

Login with existing credentials.

Request Body:

{
  "username": "johndoe",
  "password": "securepassword123"
}

Response (200):

{
  "message": "Login successful",
  "user": {
    "id": "uuid",
    "username": "johndoe",
    "email": "john@example.com",
    "created_at": "2024-01-01T00:00:00"
  },
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Get Current User

GET /api/auth/me

Get current authenticated user information.

Headers: Authorization: Bearer <token>

Response (200):

{
  "user": {
    "id": "uuid",
    "username": "johndoe",
    "email": "john@example.com",
    "created_at": "2024-01-01T00:00:00"
  }
}

Document Management

Upload PDF

POST /api/upload

Upload a PDF file.

Request: multipart/form-data

  • file: PDF file (max 100MB)

Response (201):

{
  "message": "File uploaded successfully",
  "document": {
    "id": "uuid",
    "filename": "uuid_document.pdf",
    "original_filename": "document.pdf",
    "file_size": 1024000,
    "page_count": 10,
    "user_id": "uuid",
    "is_encrypted": false,
    "metadata": {
      "title": "Document Title",
      "author": "Author Name",
      "subject": "",
      "creator": "PDF Creator",
      "producer": "PDF Producer"
    },
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T00:00:00"
  }
}

List Documents

GET /api/documents

List all documents with optional filtering and sorting.

Query Parameters:

  • search (optional): Search by filename
  • sort_by (optional): name, size, pages, created_at (default)
  • sort_order (optional): asc, desc (default)

Response (200):

{
  "documents": [
    {
      "id": "uuid",
      "filename": "uuid_document.pdf",
      "original_filename": "document.pdf",
      "file_size": 1024000,
      "page_count": 10,
      "user_id": "uuid",
      "is_encrypted": false,
      "metadata": {},
      "created_at": "2024-01-01T00:00:00",
      "updated_at": "2024-01-01T00:00:00"
    }
  ],
  "total": 1
}

Get Document

GET /api/documents/<document_id>

Get details of a specific document.

Response (200):

{
  "document": {
    "id": "uuid",
    "filename": "uuid_document.pdf",
    "original_filename": "document.pdf",
    "file_size": 1024000,
    "page_count": 10,
    "user_id": "uuid",
    "is_encrypted": false,
    "metadata": {},
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T00:00:00"
  }
}

Update Document

PUT /api/documents/<document_id>

Update document metadata (rename).

Request Body:

{
  "original_filename": "new_name.pdf",
  "metadata": {
    "title": "New Title",
    "author": "New Author"
  }
}

Response (200):

{
  "message": "Document updated successfully",
  "document": { /* updated document object */ }
}

Delete Document

DELETE /api/documents/<document_id>

Delete a document permanently.

Response (200):

{
  "message": "Document deleted successfully"
}

Download Document

GET /api/documents/<document_id>/download

Download the PDF file.

Response: PDF file download

Get Document Statistics

GET /api/documents/stats

Get statistics about documents.

Response (200):

{
  "total_documents": 42,
  "total_size": 104857600,
  "total_pages": 420,
  "average_pages": 10.0
}

Get Page Thumbnail

GET /api/documents/<document_id>/thumbnail?page=1

Get a thumbnail image of a specific page.

Query Parameters:

  • page (optional): Page number (default: 1)

Response: PNG image

Core PDF Operations

Merge PDFs

POST /api/merge

Merge multiple PDF files into one.

Request Body:

{
  "document_ids": ["uuid1", "uuid2", "uuid3"]
}

Response (201):

{
  "message": "PDFs merged successfully",
  "operation": {
    "id": "uuid",
    "operation_type": "merge",
    "status": "completed",
    "input_files": ["uuid1", "uuid2"],
    "output_file_id": "uuid",
    "parameters": {},
    "error_message": null,
    "user_id": "uuid",
    "created_at": "2024-01-01T00:00:00",
    "completed_at": "2024-01-01T00:00:05"
  },
  "document": { /* merged document object */ }
}

Split PDF

POST /api/split

Extract specific pages from a PDF.

Request Body:

{
  "document_id": "uuid",
  "pages": [1, 2, 5, 10]
}

Response (201):

{
  "message": "PDF split successfully",
  "operation": { /* operation object */ },
  "document": { /* split document object */ }
}

Rotate PDF

POST /api/rotate

Rotate pages in a PDF.

Request Body:

{
  "document_id": "uuid",
  "rotation": 90,
  "pages": "all"
}

Parameters:

  • rotation: 90, 180, or 270 degrees
  • pages: "all" or array of page numbers [1, 2, 3]

Response (201):

{
  "message": "PDF rotated successfully",
  "operation": { /* operation object */ },
  "document": { /* rotated document object */ }
}

Reorder Pages

POST /api/reorder

Reorder pages in a PDF.

Request Body:

{
  "document_id": "uuid",
  "page_order": [3, 1, 2, 5, 4]
}

Response (201):

{
  "message": "Pages reordered successfully",
  "operation": { /* operation object */ },
  "document": { /* reordered document object */ }
}

Advanced PDF Operations

Add Watermark

POST /api/watermark

Add text watermark to PDF pages.

Request Body:

{
  "document_id": "uuid",
  "text": "CONFIDENTIAL",
  "opacity": 0.3,
  "position": "diagonal"
}

Parameters:

  • text: Watermark text
  • opacity: 0.0 to 1.0 (default: 0.3)
  • position: "center", "diagonal", "top-right", "bottom-left"

Response (201):

{
  "message": "Watermark added successfully",
  "operation": { /* operation object */ },
  "document": { /* watermarked document object */ }
}

Encrypt PDF

POST /api/encrypt

Password-protect a PDF file.

Request Body:

{
  "document_id": "uuid",
  "password": "securepassword123"
}

Response (201):

{
  "message": "PDF encrypted successfully",
  "operation": { /* operation object */ },
  "document": { /* encrypted document object */ }
}

Decrypt PDF

POST /api/decrypt

Remove password protection from a PDF.

Request Body:

{
  "document_id": "uuid",
  "password": "securepassword123"
}

Response (201):

{
  "message": "PDF decrypted successfully",
  "operation": { /* operation object */ },
  "document": { /* decrypted document object */ }
}

Compress PDF

POST /api/compress

Reduce PDF file size.

Request Body:

{
  "document_id": "uuid",
  "quality": "medium"
}

Parameters:

  • quality: "low", "medium" (default), "high"

Response (201):

{
  "message": "PDF compressed successfully",
  "operation": { /* operation object */ },
  "document": { /* compressed document object */ },
  "compression_ratio": 45.5
}

PDF to Images

POST /api/pdf-to-images

Convert PDF pages to image files.

Request Body:

{
  "document_id": "uuid",
  "dpi": 200,
  "format": "png"
}

Parameters:

  • dpi: Resolution (default: 200)
  • format: "png" or "jpg"

Response (201):

{
  "message": "PDF converted to images successfully",
  "operation": { /* operation object */ },
  "images": [
    {
      "page": 1,
      "filename": "uuid_page_1.png",
      "path": "/app/uploads/uuid_page_1.png"
    }
  ]
}

Images to PDF

POST /api/images-to-pdf

Create a PDF from multiple images.

Request: multipart/form-data

  • files: Multiple image files

Response (201):

{
  "message": "Images converted to PDF successfully",
  "operation": { /* operation object */ },
  "document": { /* created PDF document object */ }
}

OCR Text Extraction

POST /api/ocr

Extract text from PDF using OCR.

Request Body:

{
  "document_id": "uuid"
}

Response (200):

{
  "message": "Text extracted successfully",
  "operation": { /* operation object */ },
  "extracted_text": [
    {
      "page": 1,
      "text": "Extracted text from page 1..."
    },
    {
      "page": 2,
      "text": "Extracted text from page 2..."
    }
  ]
}

Operations Management

List Operations

GET /api/operations

List all PDF operations.

Response (200):

{
  "operations": [
    {
      "id": "uuid",
      "operation_type": "merge",
      "status": "completed",
      "input_files": ["uuid1", "uuid2"],
      "output_file_id": "uuid",
      "parameters": {},
      "error_message": null,
      "user_id": "uuid",
      "created_at": "2024-01-01T00:00:00",
      "completed_at": "2024-01-01T00:00:05"
    }
  ]
}

Get Operation Status

GET /api/operations/<operation_id>

Get status of a specific operation.

Response (200):

{
  "operation": {
    "id": "uuid",
    "operation_type": "merge",
    "status": "completed",
    "input_files": ["uuid1", "uuid2"],
    "output_file_id": "uuid",
    "parameters": {},
    "error_message": null,
    "user_id": "uuid",
    "created_at": "2024-01-01T00:00:00",
    "completed_at": "2024-01-01T00:00:05"
  }
}

Error Responses

All endpoints may return error responses in the following format:

400 Bad Request:

{
  "error": "Invalid request parameters"
}

401 Unauthorized:

{
  "error": "Invalid credentials"
}

404 Not Found:

{
  "error": "Document not found"
}

500 Internal Server Error:

{
  "error": "Internal server error message"
}

Rate Limiting

Currently not implemented. Future feature.

Examples

Example: Upload and Merge PDFs

# 1. Upload first PDF
curl -X POST http://localhost:5000/api/upload \
  -F "file=@document1.pdf"

# Response: { "document": { "id": "uuid1", ... } }

# 2. Upload second PDF
curl -X POST http://localhost:5000/api/upload \
  -F "file=@document2.pdf"

# Response: { "document": { "id": "uuid2", ... } }

# 3. Merge PDFs
curl -X POST http://localhost:5000/api/merge \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["uuid1", "uuid2"]}'

# Response: { "message": "PDFs merged successfully", ... }

Example: Add Watermark with Authentication

# 1. Register user
curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username": "john", "email": "john@example.com", "password": "pass123"}'

# Response: { "access_token": "eyJ0...", ... }

# 2. Upload PDF (with token)
curl -X POST http://localhost:5000/api/upload \
  -H "Authorization: Bearer eyJ0..." \
  -F "file=@document.pdf"

# Response: { "document": { "id": "uuid", ... } }

# 3. Add watermark
curl -X POST http://localhost:5000/api/watermark \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJ0..." \
  -d '{"document_id": "uuid", "text": "CONFIDENTIAL", "opacity": 0.3, "position": "diagonal"}'

# Response: { "message": "Watermark added successfully", ... }

Notes

  • All file sizes are in bytes
  • All timestamps are in ISO 8601 format (UTC)
  • JWT tokens expire after 24 hours
  • Maximum file upload size is 100MB
  • Supported image formats for conversion: PNG, JPG, JPEG, GIF, BMP, TIFF
  • OCR requires Tesseract to be installed on the server
  • PDF to image conversion requires Poppler to be installed on the server