API Design Strategy: Raw Data vs. Baked-in Totals
This article discusses a common API design dilemma: whether to expose raw, normalized data or pre-computed totals with business logic. It highlights that different client needs (e.g., dashboard builders vs. quick-quote bots) necessitate different approaches. The recommended solution is to provide both, allowing clients to choose based on their specific requirements and control over business logic.
Read original on Dev.to #architectureThe API Design Dilemma: Raw vs. Processed Data
When designing APIs, a fundamental decision involves the level of data processing to expose. Should the API return granular, raw data, or should it apply business logic and return pre-computed results like totals? This choice significantly impacts client flexibility, data consistency, and the overall complexity of both the API and its consumers.
Case for Raw, Normalized Records
Exposing raw, normalized records offers maximum flexibility to integrators. Clients can apply their own business rules, perform custom calculations, and present data in diverse ways. This approach is ideal for applications like dashboards or analytics tools that require granular control and might have evolving logic. The API acts as a data provider, abstracting storage details but not business logic.
{"items": [{"jurisdiction": "pba", "status": "debt", "amount": 209250}, {"jurisdiction": "pba", "status": "voluntary_payment", "amount": 104600}]}Case for Baked-in Totals and Business Logic
Conversely, returning pre-computed totals with baked-in business logic simplifies consumption for clients that primarily need a final answer. This is particularly useful for applications like chatbots or quick summary displays where re-implementing complex rules (e.g., discount logic, rounding) is undesirable or prone to error. It ensures consistency across all consumers by centralizing critical business logic within the API layer.
Hybrid Approach: Serving Diverse Client Needs
The most robust API design often involves a hybrid approach: providing both raw data and optional pre-computed summaries. This strategy caters to a broader range of client types, from those needing granular control to those requiring immediate, trusted results, without forcing either to compromise.
The core principle is to never force the client to re-implement complex business logic to get a correct number, while also never hiding the raw data that might be needed for alternative computations or deeper analysis. Understanding your API consumers' needs is paramount in making these architectural decisions.