Proposal: expose tags through the public Budget API

[SGiersch]

Proposal: expose tags through the public Budget API

Background

The public API at /ocs/v2.php/apps/budget/api/v1 provides accounts, categories and transactions. Transactions in the Budget web interface can also have tags. Those tags are currently not available through the public API.

As a result, external clients cannot render a transaction completely: they receive its amount, vendor, description and category, but not the user-assigned tags.

Requested extension

Please include a transaction's tags as an additional field in the existing read responses:

• GET /transactions
• GET /transactions/{id}

Proposed format:

{
  "id": 20070,
  "description": "Einkauf",
  "vendor": "Beispielmarkt",
  "amount": "42.50",
  "type": "debit",
  "tags": [
    { "id": 12, "name": "Haushalt" },
    { "id": 27, "name": "Beleg geprüft" }
  ]
}

For transactions without tags, the field should always be returned as an empty array:

"tags": []

The field should not be omitted or be null. This lets clients render and filter tags without special handling.

Optional list endpoint

To allow clients to discover tags independently of existing transactions, an additional read endpoint would be useful:

GET /tags

Example response:

[
  { "id": 12, "name": "Haushalt" },
  { "id": 27, "name": "Beleg geprüft" }
]

If tags in Budget have other stable presentation data, such as a colour or sort order, those can be added as optional fields.

API contract and split transactions

Tags belong to the whole transaction, not to individual parts of a split transaction. Therefore, tags should exist only on the transaction object and should not be repeated on entries in splits.

This change is backward compatible: existing clients can ignore the new field while newer clients can display the tags.

Future extension: setting tags when creating a transaction

As a second step, it would be useful to extend POST /transactions with an optional tag_ids field. With form data, the value could be sent as a JSON array:

tag_ids=[12,27]

The API should reject unknown or inaccessible IDs with 400. This write feature is not required to display tags in a first iteration.

@otherworld-dev

[otherworld-dev]

This is done and will be in the next release. Every transaction in the API now has a tags list (empty when it has none, never null), and GET /tags lists all of your tags. I added a few fields to what you suggested: color, tag_set_id, tag_set_name, category_id, hidden and owner. Category tags can only be put on transactions in their own category, so a client needs category_id to know where a tag can be used. Setting tags with tag_ids on create isn't in yet, I want to work out how it should behave with category tags and shared accounts first.

While I was at it there are also more filters on GET /transactions (type, status, reconciled, uncategorized, tagId, amountMin, amountMax), transfers with transfer_account_id on create, and POST/DELETE /transactions/{id}/reconcile. GET /capabilities tells you which of these a server has, and the details are on the API page in the docs.

[otherworld-dev]

Setting tags is in now as well, it's on dev for the next release. POST and PATCH /transactions take tag_ids (a list of tag ids, [] on an edit removes them all), and GET /tags now also lists the tags of categories someone has shared with you, as those are the ones you can use on their shared accounts. The rules are the same as the web UI, so global tags only work on your own accounts and category tags only on transactions in that category. On a create a tag that can't be used doesn't lose the transaction, it's saved without tags and tags_error says why. tag_ids_available on GET /capabilities tells you whether a server has it, and the details are on the API page in the docs.