Analogous to addresses, also provide interface for entity transactions:

/{currency}/entities/{entity}/txs
/{currency}/entities/{entity}/txs.csv

At the moment this is a bit misleading and it remains unclear why there are two interfaces

get_address_with_tags
list_address_tags

I propose to change it as follows

get_address (returns properties of an address; if an optional "includeTags" parameter is passed, it also returns the tags)

The same should apply for the entity level

Retrieving the properties for many addresses currently requires one request per address. A possible efficiency gain is to allow bulk retrieval, e.g.,

GET /btc/addresses/12235 -> returns properties for a single address
POST /btc/addresses -> takes an array of addresses as input and returns properties for each of these addresses

The number of input addresses should, of course, be limited (e.g., 1000).

Just as it is possible to retrieve addresses and entities in bulk (by passing a list of identifiers), it should be possible to retrieve transactions in bulk.

/{currency}/txs?ids=dafa,dsafa,adf

There are two types of tx: tx_account and tx_utxo/address_tx_utxo. They are discriminated for each array item. However, they could be already discriminated one level higher, eg:

    address_txs:
      type: object
      required:
        - address_txs
      properties:
        next_page: 
          $ref: '#/components/schemas/next_page'
        oneOf:
        - $ref: '#/components/schemas/address_txs_utxo'
        - $ref: '#/components/schemas/txs_account'

The naming scheme is somehow inconsistent with the API

list_entity_neighbors
list_entity_addresses
...

list_tags_by_entity should then be named list_entity_tags`` list_tags_by_addressshould belist_address_tags`

search_paths should be oneOf "more search path", "end/leaf".

Smaller files make the API easier to read / understand.

https://davidgarcia.dev/posts/how-to-split-open-api-spec-into-multiple-files/

For UTXO ledgers it would help if the representative address determining the cluster (ID) could be returned as part of a response, at least optionally.

{
'entity': 653389348,
'repr_address': ADDRESS_DETERMINING_THE_CLUSTER_ID, 
'balance': {'eur': 0.0, 'usd': 0.0, 'value': 0},
'first_tx': {'height': 631777,
              'timestamp': 1590500176,
              'tx_hash': '0bb35c9fe8f0cbc672337287ac966f0ed35b21672dc0844c1a054a331872d2de'},
 'in_degree': 10,
 'last_tx': {'height': 632488,
             'timestamp': 1590939722,
             'tx_hash': '1f554b2cdeb156ace505e838faa41836907d40e607afbf5cea46b2d085053017'},
 'no_addresses': 5,
 'no_incoming_txs': 11,
 'no_outgoing_txs': 1,
 'out_degree': 2,
 'total_received': {'eur': 273.81, 'usd': 302.82, 'value': 3248406},
 'total_spent': {'eur': 279.21, 'usd': 310.07, 'value': 3248406}}

This clearly affects also the transformation. I propose to include the addr_id (Integer) in the schema and do the mapping to addresses during request time. Since this requires another DB query and may slow down entity retrieval, I'd offer it optionally.

Example responses provided in the Swagger UI are really useful. However, some of them contain null (/{currency}/txs) values or are missing (/{currency}/txs/{tx_hash}).

Analogous to retrieving addresses without tags, it should also be possible to retrieve entities without tags. Tags should be optional.

This affects the following interfaces:

/{currency}/addresses/{address}/entity
/{currency}/entities/{entity}

The neighbor parameter in /{currency}/entities/{entity}/links and /{currency}/entities/{entity}/links.csv is int32; however, in all other entity-related interfaces entities are of type int64. This should be harmonized.

At the moment one can use

addresses_api.get_address_entity to map an address to an entity.

Delivering the entity ID as part of an address solves this issue.

Comparing two versions of the openapi spec one could automatically determine whether the changes made are MAJOR, MINOR or PATCH.

MAJOR: not backwards compatibly
MINOR: additional functionality but backwards compatible
PATCH: bug fixes but backwards compatible

See https://semver.org

This would make it clear to users what they have to expect from api changes.

Problem: client has a list of entities (or addresses) and would like to retrieve tags for these entities (addresses) in a batch manner.

Proposed solution:

/{currency}/addresses/tags?ids=[list of strings]
/{currency}/addresses/tags.csv?ids=[list of strings]
/{currency}/entities/tags?ids=[list of ints]
/{currency}/entities/tags?ids.csv=[list of ints]

Returning address or entity objects would be much cleaner. One could also add the option "includeTags=True|False" to return them with / without tags.

Each cluster is defined by a defining address (the current entity id maps to an internal address id). This address repr_address should be returned as part of a cluster object. We need this in the tagstore.

In the underlying data model [1] we distinguish between

a.) tags directly assigned to entities (table cluster_tags)
b.) the accumulated address tags assigned to entities (table cluster_address_tags)

We could expose this on the REST interface as follows

/{currency}/entities/{entity}/tags -> returns a.)
/{currency}/entities/{entity}/address_tags -> returns b.)

OR

/{currency}/entities/{entity}/tags?type=address|entity -> returns a.) or b.)

[1] See schema https://github.com/graphsense/graphsense-transformation/blob/develop/scripts/schema_transformed.cql