API design: raw data, or totals with the business logic baked in?

When you expose a data API you hit this fork fast: do you return raw, normalized records and let the client do the math, or do you return totals with your business logic already applied? We faced it building the API for Multita, which returns the traffic fines on a vehicle, and the answer that held up was "both, on purpose".

The case for raw

Raw, normalized records are honest. Each fine comes back with its amount, status and jurisdiction, and the integrator decides what to do with them. A developer building a dashboard wants exactly this. They have their own rules, and a pre-chewed total just gets in the way.

{
  "items": [
    { "jurisdiction": "pba", "status": "debt", "amount": 209250 },
    { "jurisdiction": "pba", "status": "voluntary_payment", "amount": 104600 }
  ]
}

The case for baked-in totals

Now picture a different integrator: a WhatsApp bot that quotes a client in a single message. It does not want to reimplement your discount rules, your "which fines actually count" logic, or your rounding. It wants a number it can trust. If every integrator re-derives that number, they will all get it a little wrong, each in their own way.

Why we ship both

So the Multita API returns the normalized items plus an optional summary with the totals already computed. Raw for the people who want control, totals for the people who want an answer. The rule we follow is narrow: never force the client to reimplement business logic to get a correct number, and never hide the raw data either.

If you are designing an API, start from who integrates it. A team with its own logic and a bot that just wants the result are different customers, and you can serve both without picking a side.