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

Amatino Swift v0.0.2 Released

A new version of the Amatino API Swift library is available. Amatino Swift allows you to store double-entry accounting data in a Swift application, on iOS or MacOS.

v0.0.2 includes:

  • New Entity class, including create() & retrieve() methods
  • New Account class, including create() & retrieve() methods
  • New Transaction class, including create() & retrieve() methods
  • New Entry struct, with comprehensive initialisers
  • New GlobalUnit class, including retrieve() method
  • Expose Session class for use outside AmatinoAlpha instances
  • Unit tests for all of the above

Taken together, these changes allow you to interact with the Amatino API much more easily than in 0.0.1. 0.0.1 was fully dependent on the AmatinoAlpha class – A thin wrapper around HTTP requests that required you to deal with your own data encoding, and parse raw Data responses from the Amatino API.

Amatino Swift 0.0.2 tests
Some of the new tests included in 0.0.2

Installation

I’m still studying the best way to distribute iOS and MacOS libraries. Right now I am leaning towards CocoaPods, and would welcome any input you might have. In the mean time, compiled libraries are available on GitHub. You are also most welcome to clone the repo and compile Amatino Swift yourself.

Example Usage

Here are some examples the new capabilities available in Amatino Swift v0.0.2:

Create a Session

This is analogous to ‘logging in’. You’ll notice the session is passed as a parameter throughout following examples.

Create an Entity

Entities are beings you wish to describe with accounting information. For example, a person, company, country, or project.

More…

Still to come

The majority of objects specified in the Amatino API HTTP documentation are still not available in Amatino Swift. One glaring example is the Global Unit List – How are you supposed to retrieve Global Units if you don’t know which ones are available!?

Look out for v0.0.3 and onwards to add the missing pieces of the puzzle. Let me know how you want Amatino Swift to develop on Twitter or on the forums. Sign up to the Development Newsletter to be notified when new versions of Amatino Swift are available.

– Hugh

API v0.0.2 Released

AKA: Data in HTTP GET request bodies! Fun for the whole family!

A new version of the Amatino API is now live. API 0.0.2 makes the following changes, all of which are backwards compatible with 0.0.1. All regions have been updated to 0.0.2.

  • Added ability to parse JSON arguments from GET URL query string
  • Removed some redundant input validation on Transaction creation

Many Amatino GET actions require JSON arguments. For example, the retrieval of a Transaction requires the supply (or explicit omission) of a denominating currency.

There is substantial debate as to whether data should ever be included in the body of GET requests. Some HTTP libraries will silently strip body data from GET requests. The big dogs say GET body data is a no-no. This hit me in the face while developing Amatino Swift 0.0.2.

Rather than engaging in the debate, the Amatino API now supports both worlds. Where Amatino requires JSON data arguments to refine a request, those arguments may now be supplied via an arguments url parameter, wherein the value supplied is URL-safe Base64 encoded JSON.

The Amatino API’s version of ‘URL-safe Base64’ is the replacement of all `+` characters with `-`, and `/` with `_``=` padding characters should be left in place.

For example, say an Amatino action requires a JSON object specifying key foo with value bar. Where in 0.0.1 the only option was to supply {"foo":"bar"} in the request body, in 0.0.2 we can include arguments=eyJmb28iOiAiYmGyIn0= in the URL query string.

This is riveting stuff, but don’t worry, Amatino’s client libraries will take care of all of it for you!

Public release!

Amatino is a public application programming interface (API) providing double-entry accounting as an on demand service. You can make requests like ‘store a transaction’, ‘retrieve a ledger’, ‘create an account’, and so on: The fundamental building blocks of an accounting system.

Today, Amatino goes public! ?

The Amatino API obeys the semantic versioning (SemVer) convention. Today’s release is version 0.0.1. It is very likely that Amatino’s interfaces will be somewhat unstable for the foreseeable future. You could call it an ‘Alpha’ release, implying that not all features are ready and there are likely to be catastrophic bugs.

Despite being in an Alpha state, Amatino is feature-rich and ready to do some serious accounting work. The whole ecosystem weighs in at about 60,000 lines of code, and has been in development for several years. There are alpha versions of Swift, Python, and JavaScript (Node.JS) client libraries available, as well as comprehensive documentation of the raw HTTP API.

This blog tracks development progress, and will provide release notes and commentary as the Amatino API and its client libraries are further developed. You can get development news direct to your inbox via the development newsletter, and chat about development on the discussion forums.

You can get in contact with me directly at hugh@amatino.io or via @hugh_jeremy on Twitter. I’d love to chat about potential applications for Amatino, what features you would like to see, what bugs you have encountered (sorry!), and your general feedback.

One final note: Amatino is designed to be globally distributed, minimising latency to end-users by being physically close to them. Today I’ve deployed to servers in California and Northern Virginia. However, I can easily deploy to other regions, such as the UK or Australia. If you are keen to experiment with Amatino sitting closer to your physical location, hit me up and I’ll be happy to deploy to your region.

Enjoy!

First iteration!

This week I started testing Amatino with real people: Friends foolish enough to give in to my begging. The only thing ready for them is the sign-up process, there is a whole bunch of wiring up needed before they can interact with much else.

Nevertheless, even in just the sign-up process, the feedback came in thick and fast. Lots of little things that I would not have noticed, but other people do. So, I jumped in and changed a few things:

  • Added a password length requirement hint (thanks Andrew!)
  • Added warning about junk mail / Gmail Promotions (thanks Andrew!)
  • Tightened up application blurb wording (thanks Tim!)
  • Added prominent ‘subscribe’ button on home page (thanks Jessica!)
  • Insert ‘set username’ as the first option on account activation (thanks Jessica!)

Baby steps, right? Meanwhile, in the background, I’ve been attacking the billing system. The Amatino Api expects looks for a valid subscription before it responds to a request. At the moment, subscriptions made at https://amatino.io aren’t wired up to the billing database.

Before I make the link, I need to flesh out a bunch of boring but important billing interface elements: Change payment method, cancel subscription, change subscription type, and so on.

There is an argument to be made that this stuff is not “Minimum Viable Product”, but in my mind, ease of control over a subscription is absolutely core to Amatino. I absolutely rage out when services don’t make it easy to cancel, change, or update the way in which I pay them my hard-earned money. To that end, changes I just pushed to the Amatino Web application include:

  • Added https://amatino.io/billing/change-subscription page
  • Wrangled some details in the subscription relational data model
  • Abstracted various subscription billing objects currently used at https://amatino.io/subscribe, so that they can be used in other billing interfaces

– Hugh

Hello, world!

Amatino provides double-entry accounting as a service. It was born from a desire to create a generic, powerful, programmable accounting service. It is inspired by the brilliant GnuCash project, whose developers exhibit skill and devotion that I can only hope to match.

At time of writing, Amatino is on the cusp of a bare-bones alpha release and public unveiling. There is a blog (you’re reading it!), newsletter, discussion forum, documentation section, and most importantly, a full-featured RESTful HTTP API providing double-entry accounting as a service.

Lots of stuff is still barely functional or not functional: The Swift, C# .NET, Python, and Javascript libraries, MacOS and Windows GUI clients.

So far Amatino been built by one person, me. I’ve worked on it after-hours and on weekends, fitting it in around my full time work as a game developer at Unknown Worlds, and techy farmer at Thornleigh Farm, two companies that I adore.

It has taken about four years to get to this point. I’m terrified about revealing Amatino to the world. There is so much work to be done. I’m bursting with excitement about receiving feedback from interested people (that’s you!) about what Amatino should do and how it should develop.

– Hugh