Most teams start building a reporting API with a single endpoint that works perfectly... until real customers arrive. Then you hit timeouts, retries generate duplicates, and support can't answer basic questions like "who generated this report and when?"
This post covers the core decisions that separate a prototype reporting API from a production-ready one: synchronous vs asynchronous boundaries, delivery patterns, and multi-tenant security.
The Three Export Patterns (and When to Use Each)
Before designing API endpoints, understand that "export a report" actually covers three different use cases with different performance and reliability requirements.
Synchronous Exports: Fast and Simple
When this works:
- Report generation is consistently fast (under 5 seconds)
- You can enforce strict timeouts
- The user is actively waiting (interactive workflows)
What this looks like: Call an export endpoint, wait, receive the PDF in the response. Simple. No polling, no jobs, no complexity.
When this breaks:
- Report complexity grows (more data, more processing)
- Database queries slow down
- Users hit timeout errors and retry (creating duplicate work)
Best for: Simple reports, preview exports
Asynchronous Exports: Poll Until Ready
When you need this:
- Report generation takes variable time (30+ seconds or several minutes)
- You want predictable API response times
- Timeouts are becoming a problem
What this looks like: Call an endpoint to trigger generation, receive an export ID, poll a status endpoint until complete, then fetch the result.
The tradeoff: More complex for the API consumer (multiple calls, polling logic), but much more reliable at scale.
Best for: Complex reports, large data volumes, variable processing times
Job-Based Exports: Scheduled and Batch
When you need this:
- Scheduled delivery (daily, weekly, monthly reports)
- Batch generation (hundreds or thousands of reports)
- Background automation without user interaction
What this looks like: Create jobs with schedules or triggers, they run automatically in the background, results are delivered without polling.
The tradeoff: Most complex setup, but required for operational automation.
Best for: Scheduled reports, batch customer statements, automated compliance reports
Delivery Patterns: Beyond "Return the PDF"
Once a report is generated, how does it reach the end user? Different scenarios need different delivery methods.
Direct Download
Pattern: Export endpoint returns the PDF file directly in the response.
Best for:
- Interactive user exports (clicks "Download")
- Integration workflows where your system fetches and stores the PDF
- Synchronous exports
Limitations:
- User must be actively waiting
- No automatic retry on delivery failure
- Large files can cause timeouts
Email Delivery
Pattern: Export request includes email configuration (recipients, subject, message). System generates report and sends via email automatically.
Best for:
- Automated reports (scheduled delivery)
- Customer-facing reports (monthly statements)
- Reports where recipients don't access your system
Considerations:
- Email delivery can fail (invalid addresses, spam filters)
- Need error logging and monitoring
- Retry logic for transient failures
File Storage Delivery
Pattern: Export generates report and uploads to designated storage (Google Drive) with configured access permissions.
Best for:
- Team collaboration (shared folders)
- Automated archival
- Compliance requirements (organized storage)
Considerations:
- Permissions management (who can access)
- Folder organization (where files go)
- File consolidation (merging multiple PDFs)
Parameters and Dynamic Data: The Input Problem
Reports need inputs. The question is: where does that data come from?
Report Parameters (User-Provided Filters)
What these are: Date ranges, customer IDs, regions, product categories—user-selectable filters that control what the report shows.
API pattern: Pass as query parameters (synchronous) or in request body (asynchronous/job-based).
Best practice: Properly define your parameter schema. Parameters can be used for controlling the contents and structure of the report.
Query-Based Data (Pull from Connected Sources)
What this is: Report pulls data from configured databases, APIs, or other connected sources during generation.
Best for: High-volume reports (thousands of records), data that's already in databases, reports reused many times.
Tradeoff: Requires data source configuration upfront, but most efficient at scale.
Temporary Data Injection (Push Custom Data)
What this is: Your application computes data on-demand and sends it with the export request. Data is used once and discarded.
Best for: Computed aggregations, one-time reports, data from multiple sources that doesn't need persistence.
Tradeoff: More flexible, but less efficient for large datasets or repeated reports.
The key decision: does the data already exist in queryable form, or does your application need to assemble it on-demand?
Multi-Tenant Security: Prevent the Catastrophic Failure
The worst bug in a reporting API: Tenant A sees Tenant B's data.
Workspace/Tenant Isolation
The pattern: Every API call explicitly includes a workspace or tenant identifier. The system enforces that:
- Users can only access their assigned workspaces
- Reports are scoped to workspace boundaries
- Data queries respect workspace filters
- Generated files are stored in tenant-scoped locations
Why this matters: A single missed validation can leak sensitive data across tenant boundaries. This must be enforced at every layer, not just the UI.
Error Handling and Observability
When an export fails at 3 AM, you need to know why—without ssh-ing into servers.
Structured Error Logging
What to capture:
- Job/request identifier
- Workspace/tenant context
- Input parameters
- Failure reason (specific error, not just "failed")
- Timestamp
Why this matters: "Report failed" is useless. "Report failed: database connection timeout to finance.db after 30s" is actionable.
Status Tracking
At minimum, track:
- Queued (waiting to process)
- Processing (generation in progress)
- Completed (PDF ready)
- Failed (generation error)
For async/job exports, also track:
- Delivery status (sent, uploaded, failed)
- Retry attempts
- Completion timestamps
Best practice: Don't rely on "time since started" to calculate status. Explicitly track state transitions.
No Automatic Retry on Data Issues
Important distinction:
- Transient failures (network timeout, temporary database slowness) → Automatic retry makes sense
- Data issues (invalid parameters, missing required fields) → Flag for manual review
Automatically retrying data issues wastes resources and clutters logs. Flag them, log the specific issue, let operations fix the underlying problem.
How CxReports Addresses These Patterns
CxReports provides the building blocks for production-grade reporting APIs without requiring you to build job queues and delivery infrastructure from scratch.
Export Flexibility
CxReports supports all three export patterns:
- Direct synchronous exports for fast, interactive reports
- Asynchronous exports with polling for longer-running reports
- Job-based exports with scheduling for automated delivery
Delivery Infrastructure
Built-in delivery methods without custom integration:
- Direct download (API returns PDF)
- Email delivery (automated sending with customizable templates)
- Google Drive upload (with folder permissions and multi-file merging)
Data Source Options
Multiple ways to get data into reports:
- Query-based: Connect to SQL databases, MongoDB, APIs, Google Sheets
- Temporary data injection: Send computed data with export request, cleaned up automatically after generation
Multi-Tenant Foundation
Workspace-scoped API calls, role-based access control, and tenant isolation built into the platform—not something you need to implement yourself.
Operational Visibility
Error logging, job status tracking, and delivery monitoring without building custom observability infrastructure.
Production Checklist
Before launching your reporting API:
Export patterns:
- ✓ Defined which reports use sync vs async vs job-based export
- ✓ Documented timeout expectations for each pattern
- ✓ Implemented idempotency for duplicate prevention during automated job generation
Delivery:
- ✓ Chosen delivery methods (download, email, file storage)
- ✓ Configured delivery settings (SMTP, storage credentials)
- ✓ Implemented error handling for delivery failures
Parameters and data:
- ✓ Parameter schema defined and validated
- ✓ Data source approach chosen (query vs temporary data)
- ✓ Error messages provide actionable guidance
Security:
- ✓ Workspace/tenant boundaries enforced in all API calls
- ✓ Authentication scoped to specific workspaces
- ✓ Cross-tenant access prevented and tested
Observability:
- ✓ Error logs capture specific failure reasons
- ✓ Job status clearly tracked through lifecycle
- ✓ Monitoring alerts for delivery failures
Conclusion: Design for Production from the Start
The difference between a prototype reporting API and a production-ready one isn't complexity—it's explicit decisions about boundaries, failure modes, and operational concerns.
Key decisions:
- Export pattern: Sync for speed, async for reliability, jobs for automation
- Idempotency: Automated retries on scheduled jobs don't create duplicates
- Delivery: Match method to use case (download, email, storage)
- Data: Pull from sources or push temporarily
- Security: Workspace isolation at every layer
- Observability: Structured errors, clear status, actionable logs
Start with the right foundation: Choose a reporting platform that provides these patterns out of the box, so you can focus on your product's unique needs instead of building job queues and delivery infrastructure.
Ready to design your reporting API? Schedule a consultation to discuss your integration requirements and architectural patterns. Collapse