Amatino API v0.0.12 Now Live

Amatino API 0.0.12 is now live and serving requests at 0.0.12 resolves several issues with Transaction Version Lists (TVLs). Previously, TVLs were not operating according to the specifications in Amatino’s documentation, for either request parameters or return data. They were also at risk, under some conditions, of returning stale cached data. TVLs are now properly available.

Amatino API v0.0.10 Now Live

A new version of the Amatino API is now serving requests at 0.0.10 is probably backwards compatible with 0.0.9, because it only adds new features. However, you should not depend on backwards compatibility during the 0.0.X series of releases.

  • Add User List object at /users/list
  • Add Entity List object at /entities/list
  • Add tests for new features

Details of the User List and Entity List and how to retrieve them are available in the Amatino HTTP API documentation. Some extracts:

A User List is a collection of Users for whom the retrieving User has billing responsibility, and who were created using the Amatino API.

An Entity List enumerates the Entities that may be accessed by the retreiving User.

The use of these new objects is not immediately obvious, and they are ancillary to the core double-entry accounting functionality in Amatino. An example of Entity List usage might be displaying available Entities to a user in a client application.

Amatino API v0.0.9 now live

A new version of the Amatino API is now live around the world. 0.0.9 is substantially backwards compatible with 0.0.8, but you should not rely on backwards compatibility during the 0.0.X series of releases.

Amatino API v0.0.8 now live

A new version of the Amatino API is live in all regions. API 0.0.8 may be substantially backward compatible with 0.0.7, however, is not tested as such and relying on backwards compatibility during these 0.0.X releases is not recommended.

  • Fixed a bug which could cause a stale, cached Performance or Position to be returned after a Transaction insertion
  • Fixed a bug causing Custom Unit update requests to fail, returning a 500 code.
  • Account objects now feature a ‘Children’ parameter, which contains integer IDs of all direct child Accounts.
  • Fixed a rare condition wherein internal telemetry recording could fail due to a unique key constraint violation, causing the API to spew 500 errors in response to any request
  • Substantial code-style enhancements in the core API to ease maintainability
  • Improved test coverage over rare edge cases in Account operations

API v0.0.5 Released – Ledger Changes

A new version of the Amatino API has been deployed to all regions. 0.0.5 contains breaking changes to the Ledger object, and is not backward compatible with 0.0.4.

  • Ledgers may now only be retrieved one at a time
  • Ledgers are now paginated in rows of 500
  • Ledgers may now be returned in order of ascending or descending transaction time
  • Ledgers now require a order_oldest_first boolean argument
  • Returned Ledger root type is now a JSON Object rather than a JSON Array
  • Returned Ledger start_time and end_time will now be the start and end of the Ledger window, rather than the earliest and latest Transaction in the Ledger
  • Ledger end_time will now default to now at UTC if supplied as null
  • Ledger start_time will now default to end_time – 1 year if supplied as null
  • Fixed a bug that could cause Amatino to return a stale cached Ledger when null had previously been provided as a Ledger start time
  • Fixed a bug that caused Transactions to be stored with incorrect times (The transaction_time field was not being properly interpreted as UTC)

All the above changes also apply identically to the RecursiveLedger object.

The Amatino API obeys the Semantic Versioning convention: Any version before 1.0.0 should be considered unstable, and breaking changes may occur at any time. Even so, I don’t want to cause breaking changes unnecessarily, and don’t take this lightly.

These changes are aimed at making Ledger objects more useful in real world applications. They are the result of experimentation during development of the upcoming Amatino Swift v0.0.5.

– Hugh

Api v0.0.4 Released – Position & Performance

A new version of the Amatino API, v0.0.4, is now live and running in all regions. 0.0.4 is backward-compatible with 0.0.3, and makes the following changes:

  • Add new ‘Position‘ object
  • Add new ‘Performance‘ object
  • Fix bug causing Trees to display negative balances in <> instead of ()
  • Fix bug causing Trees to sometimes miscalculate the balance of income or expenses accounts in non-native denominations

Position & Performance were not the features I expected to be working on this week. In fact, I had not ever thought of building them at all. Last weekend, I posted Amatino to HackerNews. Lots of great feedback flowed in.

A consistent theme was: “where are the reporting tools?” In my grand-vision, Amatino is a data layer sitting below reporting in an application stack. However, an email from a prospective customer gave me a jolt. They asked: ‘Can Amatino create a balance sheet?’

Well no, it can’t, I answered. I started to type a response about how a balance sheet is too domain-specific, not a generic enough construct, and that it could be constructed in application logic out of the base components Amatino provides. Then it hit me that I was very wrong.

Abstract it back far enough, and a balance sheet is a snapshot of the position of an entity in time. We call it various names and format it in various ways, but it is at its core a very simple way of observing asset, liability, and equity accounts.

The same appears to hold true for income statements. They are, in their most generalised form, a measurement of the performance of an entity over a period of time.

Thought of in this way, balance sheets and income statements become generic objects. They are fully compatible with Amatino’s mission as a provider of generic, jurisdiction-agnostic functions for manipulating financial data.

Armed with this new thinking, I set out to add in-built capability to produce Position and Performance objects, which may be extended by an application to produce balance sheets and income statements.

Creating these objects was, fortunately, quite painless. Most of the machinery used to build them is repurposed from the Tree production line. In particular, the ability to generate a Position or Performance in any denominating unit is lifted straight from the code that builds Trees.

Trees, Positions, and Performances are by far the most complex objects Amatino can synthesise. The algorithms that compute them make my head spin.

That’s a roundabout way of saying: There will be bugs. Positions and Performances have been integrated into the API unit-testing suite at a shallow level. It will take time to build more comprehensive testing. More testing is most especially required around the production of Positions and Performances in arbitrary denominations featuring heterogeneous underlying native units.

The most important takeaway from all this is: Thank you for your feedback. By telling me what you want, you can shape Amatino’s development.

– Hugh

API v0.0.3 Released

A new version of the Amatino API has been deployed to all regions. v0.0.3 is not fully backwards compatible with v0.0.2. v0.0.3 makes the following changes:

  • Fixed a bug which could cause Balance retrieval to yield null
  • Replaced <> characters with () to denote negative values

The second change is the big bad backwards compatibility breaker. Say you recorded a debit of $10 against an asset account. In 0.0.1, Amatino would have retrieved the balance as <10.00>.  Now, it will return (10.00).

To be honest, I have no idea why I was using <> to begin with. There might have been some logic to it, perhaps because it is the default for negative numbers in PostgreSQL. But it’s not appropriate for an accounting system, where convention heavily favours ().

A screenshot showing progress in a unit test run. Many tests had to be adjusted for compatibility with 0.0.3

This kind of breaking change is not something I take lightly. Amatino obeys the Semantic Versioning convention, wherein versions before 1.0.0 may make breaking changes at any time. Regardless, I want breaking changes to be few and far between, if they must occur at all.

In future, once Amatino hits 1.0.0 and is stabilised, a breaking change would be pushed to a new major version and would require opt-in. You will never have to worry about a breaking change after 1.0.0.

– Hugh