<commit_before># uCoin HTTP API

* [Overview](#overview)
* [Merkle URLs](#merkle-urls)
* [API](#api)
  * [pks/](#pks)
      * [add](#pksadd)
      * [lookup](#pkslookup)
      * [all](#pksall)
  * [ucg/](#ucg)
      * [pubkey](#ucgpubkey)
      * [peering](#ucgpeering)
      * [peering/keys](#ucgpeeringkeys)
      * [peering/peer](#ucgpeeringpeer)
      * [peering/peers (GET)](#ucgpeeringpeers-get)
      * [peering/peers (POST)](#ucgpeeringpeers-post)
      * [peering/peers/upstream](#ucgpeeringpeersupstream)
      * [peering/peers/upstream/[PGP_FINGERPRINT]](#ucgpeeringpeersupstreampgp_fingerprint)
      * [peering/peers/downstream](#ucgpeeringpeersdownstream)
      * [peering/peers/downstream/[PGP_FINGERPRINT]](#ucgpeeringpeersdownstreampgp_fingerprint)
      * [peering/forward](#ucgpeeringforward)
      * [peering/status](#ucgpeeringstatus)
      * [tht (GET)](#ucgtht-get)
      * [tht (POST)](#ucgtht-post)
      * [tht/[PGP_FINGERPRINT]](#ucgthtpgp_fingerprint)
  * [hdc/](#hdc)
      * [amendments/current](#amendmentscurrent)
      * [amendments/current/votes](#amendmentscurrentvotes)
      * [amendments/promoted](#amendmentspromoted)
      * [amendments/promoted/[AMENDMENT_NUMBER]](#amendmentspromotedamendment_number)
      * [amendments/view/[AMENDMENT_ID]/members](#amendmentsviewamendment_idmembers)
      * [amendments/view/[AMENDMENT_ID]/self](#amendmentsviewamendment_idself)
      * [amendments/view/[AMENDMENT_ID]/voters](#amendmentsviewamendment_idvoters)
      * [amendments/view/[AMENDMENT_ID]/signatures](#amendmentsviewamendment_idsignatures)
      * [amendments/votes (GET)](#amendmentsvotes-get)
      * [amendments/votes (POST)](#amendmentsvotes-post)
      * [amendments/votes/[AMENDMENT_ID]](#amendmentsvotesamendment_id)
      * [coins/[PGP_FINGERPRINT]/list](#coinspgp_fingerprintlist)
      * [coins/[PGP_FINGERPRINT]/view/[COIN_NUMBER]](#coinspgp_fingerprintviewcoin_number)
      * [coins/[PGP_FINGERPRINT]/view/[COIN_NUMBER]/history](#coinspgp_fingerprintviewcoin_numberhistory)
      * [transactions/process](#transactionsprocess)
      * [transactions/all](#transactionsall)
      * [transactions/keys](#transactionskeys)
      * [transactions/last](#transactionslast)
      * [transactions/last/[count]](#transactionslastcount)
      * [transactions/sender/[PGP_FINGERPRINT]](#transactionssenderpgp_fingerprint)
      * [transactions/sender/[PGP_FINGERPRINT]/last](#transactionssenderpgp_fingerprintlast)
      * [transactions/sender/[PGP_FINGERPRINT]/last/[count]](#transactionssenderpgp_fingerprintlastcount)
      * [transactions/sender/[PGP_FINGERPRINT]/issuance](#transactionssenderpgp_fingerprintissuance)
      * [transactions/sender/[PGP_FINGERPRINT]/issuance/last](#transactionssenderpgp_fingerprintissuancelast)
      * [transactions/sender/[PGP_FINGERPRINT]/issuance/dividend](#transactionssenderpgp_fingerprintissuancedividend)
      * [transactions/sender/[PGP_FINGERPRINT]/issuance/dividend/[AM_NUMBER]](#transactionssenderpgp_fingerprintissuancedividendam_number)
      * [transactions/sender/[PGP_FINGERPRINT]/issuance/fusion](#transactionssenderpgp_fingerprintissuancefusion)
      * [transactions/sender/[PGP_FINGERPRINT]/transfert](#transactionssenderpgp_fingerprinttransfert)
      * [transactions/recipient/[PGP_FINGERPRINT]](#transactionsrecipientpgp_fingerprint)
      * [transactions/view/[TRANSACTION_ID]](#transactionsviewtransaction_id)

## Overview

Data is made accessible through an HTTP API mainly inspired from [OpenUDC_exchange_formats draft](https://github.com/Open-UDC/open-udc/blob/master/docs/OpenUDC_exchange_formats.draft.txt), and has been adapted to fit uCoin specificities.

    http[s]://Node[:port]/...
    |-- pks/
    |   |-- add
    |   |-- all
    |   `-- lookup
    |-- ucg/
    |   |-- pubkey
    |   |-- peering
    |   |   |-- keys
    |   |   |-- forward
    |   |   |-- status
    |   |   |-- peer
    |   |   `-- peers/
    |   |       |-- upstream/
    |   |       |   `-- [PGP_FINGERPRINT]
    |   |       `-- downstream/
    |   |           `-- [PGP_FINGERPRINT]
    |   `-- tht/
    |       `-- [PGP_FINGERPRINT]
    `-- hdc/
        |-- amendments/
        |   |-- current/
        |   |   `-- votes
        |   |-- promoted
        |   |   `-- [AMENDMENT_NUMBER]
        |   |-- view/
        |   |   `-- [AMENDMENT_ID]/
        |   |       |-- members
        |   |       |-- self
        |   |       `-- voters
        |   |       `-- signatures
        |   `-- votes/
        |   |   `-- [AMENDMENT_ID]/
        |   |       `-- signatures
        |-- coins/
        |   `-- [PGP_FINGERPRINT]/
        |       |-- list
        |       `-- view/
        |           `-- [COIN_NUMBER]/
        |               `-- history
        `-- transactions/
            |-- process
            |-- all
            |-- keys
            |-- last/
            |   `-- [count]
            |-- sender/
            |   `-- [PGP_FINGERPRINT]/
            |       |-- last/
            |           `-- [count]
            |       |-- transfert
            |       `-- issuance/
            |           |-- last
            |           |-- fusion
            |           `-- dividend/
            |               `-- [AM_NUMBER]
            |-- recipient/
            |   `-- [PGP_FINGERPRINT]
            `-- view/
                `-- [TRANSACTION_ID]

## Merkle URLs

Merkle URL is a special kind of URL applicable for resources:

* `pks/all`
* `ucg/tht (GET)`
* `ucg/peering/peers (GET)`
* `ucg/peering/keys`
* `hdc/amendments/current/votes`
* `hdc/amendments/view/[AMENDMENT_ID]/members`
* `hdc/amendments/view/[AMENDMENT_ID]/voters`
* `hdc/amendments/view/[AMENDMENT_ID]/signatures`
* `hdc/amendments/votes/[AMENDMENT_ID]`
* `hdc/transactions/all`
* `hdc/transactions/keys`
* `hdc/transactions/sender/[PGP_FINGERPRINT]`
* `hdc/transactions/sender/[PGP_FINGERPRINT]/issuance`
* `hdc/transactions/sender/[PGP_FINGERPRINT]/issuance/dividend`
* `hdc/transactions/sender/[PGP_FINGERPRINT]/issuance/dividend/[AM_NUMBER]`
* `hdc/transactions/sender/[PGP_FINGERPRINT]/issuance/fusion`
* `hdc/transactions/sender/[PGP_FINGERPRINT]/transfert`
* `hdc/transactions/recipient/[PGP_FINGERPRINT]`

Such kind of URL returns Merkle tree hashes informations. In uCoin, Merkle trees are an easy way to detect unsynced data and where the differences come from. For example, `hdc/amendments/view/[AMENDMENT_ID]/members` is a Merkle tree whose leaves are hashes of members key fingerprint sorted ascending way. Thus, if any new key is added, a branch of the tree will see its hash modified and propagated to the root hash. Change is then easy to detect.

For commodity issues, this URL uses query parameters to retrieve partial data of the tree, as most of the time all the data is not required. uCoin Merkle tree has a determined number of parent nodes (given a number of leaves), which allows to ask only for interval of them.

Here is an example of members Merkle tree with 5 members (taken from [Tree Hash EXchange format (THEX)](http://web.archive.org/web/20080316033726/http://www.open-content.net/specs/draft-jchapweske-thex-02.html)):

                       ROOT=H(H+E)
                        /        \
                       /          \
                 H=H(F+G)          E
                /       \           \
               /         \           \
        F=H(A+B)         G=H(C+D)     E
        /     \           /     \      \
       /       \         /       \      \
      A         B       C         D      E


    Note: H() is some hash function

Where A,B,C,D,E are already hashed data.

With such a tree structure, uCoin consider the tree has exactly 6 nodes: `[ROOT,H,E,F,G,E]`. Nodes are just an array, and for a Lambda Server LS1, it is easy to ask for the values of another server LS2 for level 1 (`H` and `E`, the second level): it requires nodes interval `[1;2]`.

Hence it is quite easy for anyone who wants to check if a `Z` member joined the uCoin community as it would alter the `E` branch of the tree:

                        ROOT'=H(H+E')
                        /            \
                       /              \
                 H=H(F+G)              E'
                /       \               \
               /         \               \
        F=H(A+B)          G=H(C+D)       E'=H(E+Z)
        /     \           /     \         /     \
       /       \         /       \       /       \
      A         B       C         D     E         Z

`ROOT` changed to `ROOT'`, `E` to `E'`, but `H` did not. The whole `E'` branch should be updated with the proper new data.

For that purpose, Merkle URL defines different parameters and results:

**Parameters**

Parameter | Description
--------- | -----------
`lstart` | Integer value that indicates the starting level (inclusive) of hashes to be returned. `lstart` start from `0` (`ROOT` hash). Defaults to `0`.
`lend` | Integer value that indicates the ending level (exclusive) of hashes to be returned. `lend` start from `0` (`ROOT` hash). Defaults to `0`.
`start` | Integer value that defines the start range (inclusive) of desired hashes for each level.
`end` | Integer value which  that defines the end range (exclusive) of desired hashes for each level.
`extract` | Boolean value that asks for result to inspect leaves and return both **hash** *and* **original content** values. Ignore `lstart` and `lend` parameters.

**Returns**
<commit_msg>Update HTTP API (merkle parameters)<commit_after># uCoin HTTP API

* [Overview](#overview)
* [Merkle URLs](#merkle-urls)
* [API](#api)
  * [pks/](#pks)
      * [add](#pksadd)
      * [lookup](#pkslookup)
      * [all](#pksall)
  * [ucg/](#ucg)
      * [pubkey](#ucgpubkey)
      * [peering](#ucgpeering)
      * [peering/keys](#ucgpeeringkeys)
      * [peering/peer](#ucgpeeringpeer)
      * [peering/peers (GET)](#ucgpeeringpeers-get)
      * [peering/peers (POST)](#ucgpeeringpeers-post)
      * [peering/peers/upstream](#ucgpeeringpeersupstream)
      * [peering/peers/upstream/[PGP_FINGERPRINT]](#ucgpeeringpeersupstreampgp_fingerprint)
      * [peering/peers/downstream](#ucgpeeringpeersdownstream)
      * [peering/peers/downstream/[PGP_FINGERPRINT]](#ucgpeeringpeersdownstreampgp_fingerprint)
      * [peering/forward](#ucgpeeringforward)
      * [peering/status](#ucgpeeringstatus)
      * [tht (GET)](#ucgtht-get)
      * [tht (POST)](#ucgtht-post)
      * [tht/[PGP_FINGERPRINT]](#ucgthtpgp_fingerprint)
  * [hdc/](#hdc)
      * [amendments/current](#amendmentscurrent)
      * [amendments/current/votes](#amendmentscurrentvotes)
      * [amendments/promoted](#amendmentspromoted)
      * [amendments/promoted/[AMENDMENT_NUMBER]](#amendmentspromotedamendment_number)
      * [amendments/view/[AMENDMENT_ID]/members](#amendmentsviewamendment_idmembers)
      * [amendments/view/[AMENDMENT_ID]/self](#amendmentsviewamendment_idself)
      * [amendments/view/[AMENDMENT_ID]/voters](#amendmentsviewamendment_idvoters)
      * [amendments/view/[AMENDMENT_ID]/signatures](#amendmentsviewamendment_idsignatures)
      * [amendments/votes (GET)](#amendmentsvotes-get)
      * [amendments/votes (POST)](#amendmentsvotes-post)
      * [amendments/votes/[AMENDMENT_ID]](#amendmentsvotesamendment_id)
      * [coins/[PGP_FINGERPRINT]/list](#coinspgp_fingerprintlist)
      * [coins/[PGP_FINGERPRINT]/view/[COIN_NUMBER]](#coinspgp_fingerprintviewcoin_number)
      * [coins/[PGP_FINGERPRINT]/view/[COIN_NUMBER]/history](#coinspgp_fingerprintviewcoin_numberhistory)
      * [transactions/process](#transactionsprocess)
      * [transactions/all](#transactionsall)
      * [transactions/keys](#transactionskeys)
      * [transactions/last](#transactionslast)
      * [transactions/last/[count]](#transactionslastcount)
      * [transactions/sender/[PGP_FINGERPRINT]](#transactionssenderpgp_fingerprint)
      * [transactions/sender/[PGP_FINGERPRINT]/last](#transactionssenderpgp_fingerprintlast)
      * [transactions/sender/[PGP_FINGERPRINT]/last/[count]](#transactionssenderpgp_fingerprintlastcount)
      * [transactions/sender/[PGP_FINGERPRINT]/issuance](#transactionssenderpgp_fingerprintissuance)
      * [transactions/sender/[PGP_FINGERPRINT]/issuance/last](#transactionssenderpgp_fingerprintissuancelast)
      * [transactions/sender/[PGP_FINGERPRINT]/issuance/dividend](#transactionssenderpgp_fingerprintissuancedividend)
      * [transactions/sender/[PGP_FINGERPRINT]/issuance/dividend/[AM_NUMBER]](#transactionssenderpgp_fingerprintissuancedividendam_number)
      * [transactions/sender/[PGP_FINGERPRINT]/issuance/fusion](#transactionssenderpgp_fingerprintissuancefusion)
      * [transactions/sender/[PGP_FINGERPRINT]/transfert](#transactionssenderpgp_fingerprinttransfert)
      * [transactions/recipient/[PGP_FINGERPRINT]](#transactionsrecipientpgp_fingerprint)
      * [transactions/view/[TRANSACTION_ID]](#transactionsviewtransaction_id)

## Overview

Data is made accessible through an HTTP API mainly inspired from [OpenUDC_exchange_formats draft](https://github.com/Open-UDC/open-udc/blob/master/docs/OpenUDC_exchange_formats.draft.txt), and has been adapted to fit uCoin specificities.

    http[s]://Node[:port]/...
    |-- pks/
    |   |-- add
    |   |-- all
    |   `-- lookup
    |-- ucg/
    |   |-- pubkey
    |   |-- peering
    |   |   |-- keys
    |   |   |-- forward
    |   |   |-- status
    |   |   |-- peer
    |   |   `-- peers/
    |   |       |-- upstream/
    |   |       |   `-- [PGP_FINGERPRINT]
    |   |       `-- downstream/
    |   |           `-- [PGP_FINGERPRINT]
    |   `-- tht/
    |       `-- [PGP_FINGERPRINT]
    `-- hdc/
        |-- amendments/
        |   |-- current/
        |   |   `-- votes
        |   |-- promoted
        |   |   `-- [AMENDMENT_NUMBER]
        |   |-- view/
        |   |   `-- [AMENDMENT_ID]/
        |   |       |-- members
        |   |       |-- self
        |   |       `-- voters
        |   |       `-- signatures
        |   `-- votes/
        |   |   `-- [AMENDMENT_ID]/
        |   |       `-- signatures
        |-- coins/
        |   `-- [PGP_FINGERPRINT]/
        |       |-- list
        |       `-- view/
        |           `-- [COIN_NUMBER]/
        |               `-- history
        `-- transactions/
            |-- process
            |-- all
            |-- keys
            |-- last/
            |   `-- [count]
            |-- sender/
            |   `-- [PGP_FINGERPRINT]/
            |       |-- last/
            |           `-- [count]
            |       |-- transfert
            |       `-- issuance/
            |           |-- last
            |           |-- fusion
            |           `-- dividend/
            |               `-- [AM_NUMBER]
            |-- recipient/
            |   `-- [PGP_FINGERPRINT]
            `-- view/
                `-- [TRANSACTION_ID]

## Merkle URLs

Merkle URL is a special kind of URL applicable for resources:

* `pks/all`
* `ucg/tht (GET)`
* `ucg/peering/peers (GET)`
* `ucg/peering/keys`
* `hdc/amendments/current/votes`
* `hdc/amendments/view/[AMENDMENT_ID]/members`
* `hdc/amendments/view/[AMENDMENT_ID]/voters`
* `hdc/amendments/view/[AMENDMENT_ID]/signatures`
* `hdc/amendments/votes/[AMENDMENT_ID]`
* `hdc/transactions/all`
* `hdc/transactions/keys`
* `hdc/transactions/sender/[PGP_FINGERPRINT]`
* `hdc/transactions/sender/[PGP_FINGERPRINT]/issuance`
* `hdc/transactions/sender/[PGP_FINGERPRINT]/issuance/dividend`
* `hdc/transactions/sender/[PGP_FINGERPRINT]/issuance/dividend/[AM_NUMBER]`
* `hdc/transactions/sender/[PGP_FINGERPRINT]/issuance/fusion`
* `hdc/transactions/sender/[PGP_FINGERPRINT]/transfert`
* `hdc/transactions/recipient/[PGP_FINGERPRINT]`

Such kind of URL returns Merkle tree hashes informations. In uCoin, Merkle trees are an easy way to detect unsynced data and where the differences come from. For example, `hdc/amendments/view/[AMENDMENT_ID]/members` is a Merkle tree whose leaves are hashes of members key fingerprint sorted ascending way. Thus, if any new key is added, a branch of the tree will see its hash modified and propagated to the root hash. Change is then easy to detect.

For commodity issues, this URL uses query parameters to retrieve partial data of the tree, as most of the time all the data is not required. uCoin Merkle tree has a determined number of parent nodes (given a number of leaves), which allows to ask only for interval of them.

Here is an example of members Merkle tree with 5 members (taken from [Tree Hash EXchange format (THEX)](http://web.archive.org/web/20080316033726/http://www.open-content.net/specs/draft-jchapweske-thex-02.html)):

                       ROOT=H(H+E)
                        /        \
                       /          \
                 H=H(F+G)          E
                /       \           \
               /         \           \
        F=H(A+B)         G=H(C+D)     E
        /     \           /     \      \
       /       \         /       \      \
      A         B       C         D      E


    Note: H() is some hash function

Where A,B,C,D,E are already hashed data.

With such a tree structure, uCoin consider the tree has exactly 6 nodes: `[ROOT,H,E,F,G,E]`. Nodes are just an array, and for a Lambda Server LS1, it is easy to ask for the values of another server LS2 for level 1 (`H` and `E`, the second level): it requires nodes interval `[1;2]`.

Hence it is quite easy for anyone who wants to check if a `Z` member joined the uCoin community as it would alter the `E` branch of the tree:

                        ROOT'=H(H+E')
                        /            \
                       /              \
                 H=H(F+G)              E'
                /       \               \
               /         \               \
        F=H(A+B)          G=H(C+D)       E'=H(E+Z)
        /     \           /     \         /     \
       /       \         /       \       /       \
      A         B       C         D     E         Z

`ROOT` changed to `ROOT'`, `E` to `E'`, but `H` did not. The whole `E'` branch should be updated with the proper new data.

For that purpose, Merkle URL defines different parameters and results:

**Parameters**

Parameter | Description
--------- | -----------
`lstart` | Integer value that indicates the starting level (inclusive) of hashes to be returned. `lstart` start from `0`. Defaults to `0` (`ROOT` hash).
`lend` | Integer value that indicates the ending level (exclusive) of hashes to be returned. `lend` start from `0`. Defaults to `1` (`ROOT` hash).
`start` | Integer value that defines the start range (inclusive) of desired hashes for each level. Defaults to `0`.
`end` | Integer value which  that defines the end range (exclusive) of desired hashes for each level. Defaults to `leavesCount` of the Merkle.
`extract` | Boolean value that asks for result to inspect leaves and return both **hash** *and* **original content** values. Ignore `lstart` and `lend` parameters.

**Returns**

{'fraction_non_alphanumeric': 0.13391157182145125, 'fraction_numerical': 0.0029088216627882377, 'mean_word_length': 2.2092668024439917, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 30, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4352754', 'n_tokens_mistral': 6501, 'n_tokens_neox': 6113, 'n_words': 1161}