Amatino API v0.0.23

A new version of the Amatino API is serving requests at v0.0.23 is mostly backwards compatible with v0.0.22.

  • Responses from /accounts will provide informative error messages when requests yield 400. In the past, such requests would only provide a generic “400 - Bad Request” response, making debugging difficult. You can now expect precise errors, such as “Missing "name" key” or “"description" value too long – max length 4096 characters.”
  • Fixed a bug wherein Accounts could sometimes be returned with missing keys
  • Account deletion requests now return data consistent with documentation. They previously returned an undocumented data structure
  • Account update requests previously demanded a unit key. This was inconsistent with global_unit_id demanded elsewhere, and with documentation. Update requests now demand the global_unit_id key as documented.
  • Nullable Account request fields (e.g. parent_account_id) are now optional. That is, you no longer need to include the key with a null value. You may continue to do so.
  • Eliminated PATCH support for /accounts. The method was seldom used, and offered little value given Transaction data cannot be destroyed through Account deletion.

Amatino Python v0.0.18

v0.0.18 makes the following changes. Code currently running on v0.0.16 should generally be backwards compatible with v0.0.18.

  • Requests for resources that Amatino API cannot find will now raise a ResourceNotFound error, rather than a generic urllib.HTTPError. ResourceNotFound is a subclass of AmatinoError, allowing you to catch non-existent resources along with other Amatino library exceptions.
  • Internally, ApiRequest.response_data is now immutable
  • In previous versions, ApiRequest responded to an undocumented command line argument --debug. This argument is common and may clash with application command line arguments, causing unexpected behaviour. The argument has been renamed --amatino-debug.
  • GlobalUnit no longer has a .session property
  • GlobalUnit now implements the equality operator via __eq__()
  • Added a new class: GlobalUnitConstants, which enumerates a subset of common GlobalUnits. For example:
# Previously, the only way to get USD was...
usd = GlobalUnit.retrieve(5, session)
# Now you can also...
usd = GlobalUnitConstants.USD

Install Amatino Python via Pip:

pip install --upgrade amatino

Amatino API v0.0.21

Changes in v0.0.21:

  • Requests with malformed JSON bodies will now yield informative 400 class error responses. Previously, they would yield generic 400 or even 500, depending on the nature of the malformation.
  • Fixed a regression wherein /trees requests would be rejected where the JSON payload was encoded in the URL under the arguments key.
  • Where Base64-encoded JSON data is that last key/value pair in the URL, Amatino API will now tolerate absent padding characters.

v0.0.20 compatible code is compatible with v0.0.21.

Amatino API v0.0.20

v0.0.20 is now serving requests at

  • Amatino API will return compliant Access-Control-Allow-X headers on response to Options requests. The return code will be 204.
  • Requests for to /trees yielding 400 responses will now provide informative error messages. Previously, a generic “bad request” response was returned.

v0.0.19 compatible code is compatible with v0.0.20. Enjoy!

Amatino API 0.0.19 Released

0.0.19 modifies Entity listing behaviour. It is now possible to search for Entities by name. The manner in which Amatino conveys listed Entities changed, and this new manner will be rolled out across all Amatino objects in time.

0.0.18 code is not backwards compatible with API 0.0.19 with respect to Entity listing.

New Entity Listing Model

Prior to 0.0.19, a request to /entities/list would return a package of the form:

    'entities': [...]
    'number_of_pages': [integer],
    'page': [integer],
    'state': [string],
    'generated_time': [string]

… Wherein the Entity objects were returned under the "entities" key. In 0.0.19, Entities are now returned as a list of Entity objects. There is no encapsulating package providing list metadata.

Instead, the Entity object itself is aware of its own disposition with respect to a listing query. Inside the Entity object is a new keyed value, "disposition":

    "entity_id": [string],
    "name": [string],
    "owner": [integer],
    "description": [string],
    "region_id": [integer],
    "permissions_graph": [object],
    "disposition": {
        "sequence": [integer],
        "count": [integer],
        "limit": [integer],
        "offset": [integer]

The meanings of the four integers inside the Disposition are:

Limit: The maximum number of objects returned in response to the request.

Offset: The sequence number at which the returned objects start.

Count: The total number of objects having attributes that satisfy the request. For example, if you request all Entities whose name starts with "Great", with a limit of 10 and offset 0, and there are 12 entities with such names, you will receive a "count" value of 12 and a "limit" value of 10.

Sequence: The unique position of this object within all possibly returned objects satisfying the request conditions.

In future, this model will be adopted by all Amatino objects that may be listed. That is, they will all include a Disposition object.

Searching by Name

The /entities path now accepts a new URL parameter: name. The value for name can be any string value between 3 and 64 characters long. It is optional.

Amatino will search for all Entities with a case-insensitive name that contains the specified string. For example, "name=orporation" will return Entities with name "Excellent Corporation" and "PROFITABLE CORPORATION LTD".

You can omit the name key entirely.

0.0.19 Compatible Libraries

New versions of Amatino client libraries are available, compatible with API 0.0.19:


Amatino Python 0.0.16

  • Added Entity.retrieve_list() -> List[Entity] method
  • Fixed bad type annotation, Entity.retrieve() now hints at return type of Optional[Entity]
  • Added Disposition class
  • Added Entity.disposition property
  • Remove debug print from Signature computation

Amatino Swift 0.0.14

  • Removed deprecated EntityList
  • Added EntityList.retrieveList(), available in both error-first and and Result callback forms
  • Added Disposition struct
  • Added Entity.disposition property
  • Removed EntityListScope enum
  • Added State enum

Amatino API v0.0.18 [Heavily Breaking Changes]

A new version of the Amatino API has been deployed. 0.0.18 contains breaking changes – Any code interfacing with versions below 0.0.18 will not work with 0.0.18.

0.0.18 modifies the way HMAC signatures are computed. JSON bodies are no longer included in signature computation. Their inclusion was causing intermittent issues for customers: Seemingly at random, requests would be met with 401 - Not Authenticated responses.

The inclusion of JSON bodies in HMAC computation was, in hindsight, a poor decision. By definition, JSON object key/value ordering is indeterminate. If a key/value pair happens to be parsed in a different order on either side of the client / API connection, the request would fail.

Along with API 0.0.18, the following new client libraries are available:

Each of these libraries supports API 0.0.18.

We never want to make breaking changes like this. We understand how frustrating it is to have integrations break, and apologise profusely. While Amatino is in an “alpha” state (pre v1.0.0), we will make these changes as rarely as possible. After v1.0.0, breaking changes will only be made with prior versions remaining online.

Amatino API v0.0.17 Released

Hot on the heels of 0.0.16, 0.0.17 delivers two changes:

  • Fixed a bug that caused Account create/update requests to fail if they contained a colour value formed as per documentation
  • Account creation/update requests will now fail with informative error messages, such as “description too long, max value 1024”, rather than a generic “400 – Bad Request”


Amatino API v0.0.16 Released

HTTP API update! 0.0.16 is now out in the wild, serving requests. Here’s what it includes:

  • Fixed a bug causing unauthorised and unauthenticated requests to return 500 errors rather than 401 / 403
  • Server header now includes the API version number
  • Fixed a bug causing Region listing to fail in certain unusual circumstances
  • Fixed a bug causing Entity permission records to enter an invalid state when that Entity was updated with a null record
  • Fixed a bug causing arbitrary requests to 500, due to a fault in Amatino’s billing system
  • Added various tests to catch aforementioned failure cases in future

Enjoy! And please continue to report bugs: @AmatinoAPI on Twitter /