Cloud & Automation
Designing a Report Engine for UI and API Consumers
Design one governed report backend for interactive UI pages, external APIs, downloads and large asynchronous exports.
On this page
Most report platforms end up with two kinds of consumer: people using a web or mobile interface, and systems calling an API. Each wants the same business numbers, but in a different shape. The design goal is one report engine that owns the report logic once and adapts only the delivery to each consumer.
One backend
When possible, UI and API consumers use the same report engine. Interactive UI follows UI to API to report engine to JSON or page data. Export follows UI or API to a report request, generated CSV or file, and a protected download URL. Shared validation and authorization prevent the UI and API from developing conflicting data rules.
Shared report logic
The report definition belongs to the engine, not to either consumer: allowed dimensions and filters, the approved query template, date-range rules, row limits, and the meaning of each measure. The UI and the API both send intent to that definition. If the web application calculates its own totals or applies its own filters, the UI and the API will eventually disagree about the same report.
Avoid duplicate report implementations, such as one query for the dashboard and another for the export endpoint. Duplicates drift: a fix to a filter or a measure lands in one path and not the other, and consumers receive different answers to the same question. One definition with several delivery contracts is easier to test, secure, and change.
Consumer contracts
Interactive screens need pagination, stable sorting, compact projections, cancellation, and predictable latency. Exports need format selection, larger limits, asynchronous execution, storage, expiration, and download authorization. The same logical report definition can support both while using different delivery contracts.
| Need | UI consumer | API consumer |
|---|---|---|
| Response shape | Compact JSON page with only displayed columns | Complete, documented schema |
| Size | Small pages for one screen | Larger pages or a file export |
| Latency | Fast enough for an interactive view | Can wait for asynchronous completion |
| Formats | JSON or page data | JSON, CSV or another allowed file format |
| Lifetime | Discarded when the user leaves the page | Stored result with an expiry and download link |
Pagination and sorting
Pagination keeps interactive responses small and bounded. Each page must come from a stable sort, so the same request returns the same rows in the same order; add a unique key as the final sort column when the visible sort column has ties. Accept sort fields from an allow-list, as with dimensions and filters, rather than passing a column name from the client into a query.
API consumers often need the whole result rather than one screen. Give them larger pages with the same stable ordering, or an export, instead of letting them walk thousands of small UI-sized pages.
Validation
Convert display-by values such as Date, Channel, or Account into an allow-listed enum. Validate start and end dates, maximum range, allowed filters, tenant access, format, and row limits. The client sends intent, never query fragments. The backend uses parameterized statements or controlled query builders.
Authentication and authorization boundaries
UI users and API clients authenticate differently: an interactive user signs in, while an integration presents a client identity or API key. Both should resolve to the same authorization decision inside the engine: which tenant the caller belongs to, which reports it may run, and which filters it may apply. Derive tenant identity from authenticated claims or a trusted service mapping, never from a tenant_id the browser or caller supplies.
Download URLs for stored results are short lived and checked against the requesting tenant. Write an audit event for report access, and keep secrets and sensitive filter values out of ordinary logs.
Cache reuse
Because both consumers call one engine, they can share cached results. Build the cache key from trusted tenant identity, report type, normalized parameters, format, and report version, so the same logical request from the UI or the API resolves to the same entry. Include tenant identity in every key, and authorize a cache hit as strictly as a fresh query. Pagination and sorting change what a page returns, so either include them in the key for page-level caching or cache the full result and page through it.
Rate limiting
Apply limits per consumer from authenticated identity: a burst of API calls from one integration should not slow every interactive user. Interactive pages and large exports also deserve separate budgets, because one export can cost as much as many page views. Return an explicit throttling response with guidance instead of letting requests time out, and route heavy work to the asynchronous option below.
Async option
For large work, POST /reports can return 202 Accepted with reportRequestId. GET /reports/{id} returns status, and GET /reports/{id}/download returns a short-lived authorized result. Small bounded requests can remain synchronous; forcing every interaction through a job queue adds needless complexity.
Tradeoffs and failure modes
More flexible requests improve usefulness but expand the security and performance surface. Prefer explicit report contracts and allow-listed variation over an unrestricted query interface for either consumer. More caching reduces query load but creates freshness and invalidation questions that both consumers inherit.
Watch for partial success: a report can finish after its caller disconnects, and a cache write can fail after a valid result was returned. Model those outcomes explicitly, and do not let partial output be mistaken for a complete export.
Operational review questions
Before release, confirm that the UI and the API produce identical numbers for the same report and parameters, that both paths go through the same validation and authorization, and that a request ID connects a user’s screen or an API call to the execution behind it. Check that limits produce explicit responses for both consumers, that exports expire as intended, and that a change to one report definition reaches every consumer at once.
Was this helpful?
What could be better?
Thanks — that helps me improve Javi Builds.
Continue learning
- Cheat sheetHTTP Status Codes for DevelopersInterpret and use HTTP status codes correctly when building and troubleshooting APIs, with practical guidance for success, redirects, client errors, server errors, retries, and API design decisions.Open cheat sheet
- ArticleReport Engine Architecture: Request to ResultTrace a report request through gateway, security, validation, cache, Fabric query, result construction and monitoring.Read article
What should I build next?
I'm building Javi Builds around practical problems data engineers actually face. Tell me what you'd like to see next.
Stay in the loop
Get the Javi Builds updates you actually care about.
Check your inbox
I sent you a confirmation link. Your subscription will be active after you confirm it.