liveBook · Manning

Account balance

As explained in The Design of Web APIs, Second Edition

A balance is the calculated amount of money held in or associated with a bank account according to a particular banking calculation method.

A balance is the calculated amount of money associated with a bank account. Banking systems may provide multiple balances because calculation methods differ, but exposing every option can burden consumers with choosing among them. section 8.4.1

Choose a single, commonly used balance when users are non-experts or use cases do not distinguish balance types. Retain multiple balances when those distinctions matter, especially for expert consumers. section 8.4.1

A self-interpreting balance model

A balance amount should identify its currency rather than expose an unexplained number such as 123. When several balances are needed, represent them as a balances array, for example objects typed "value-date" or "expected", with a Boolean default flag on the commonly used balance. section 8.4.2 section 8.6.2

Figure 8.15 Different properties representing the same type of data may be grouped into an array.
figure

Use the array structure to make multiple balance types explicit and easier to browse in code or a JSON viewer. section 8.6.2

How The Design of Web APIs, Second Edition covers it

How deep it goes
Explains balance selection, supporting currency metadata, array grouping, and when embedded lists should become separate resources.
Examples
Uses value-date and expected balances, currency metadata, default flags, and a balances array as concrete modeling examples.
What you can do after
Build balance representations that remain meaningful for consumers while supporting necessary banking distinctions.
How it connects
Connects balances with bank accounts, currencies, arrays, default values, resource models, filtering, and pagination.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of The Design of Web APIs, Second Edition. The section links point to the parts of the book it draws on.