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.

By JaviPublished 9 min readIntermediate

Web, mobile and external API clients sharing one report engine

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.

Tags

  • Data Architecture
  • API
  • Reporting
  • CSV
  • Caching
  • Multi-Tenancy