1## Census HTTP service
  2
  3Reference implementation of a voting census service running on the Vocdoni platform
  4
  5## Compile
  6
  7In a GO ready environment:
  8
  9```
 10go get -u github.com/vocdoni/dvote-census/...
 11go build -o censusHttpService github.com/vocdoni/dvote-census/cmd/censushttp
 12```
 13
 14## Usage
 15
 16`./censusHttpService <port> <censusId>[:pubKey] [<censusId>[:pubKey] ...]`
 17
 18Example
 19
 20```
 21./censusHttpService 1500 Got_Favorite
 222019/02/12 10:20:16 Starting process HTTP service on port 1500 for namespace GoT_Favorite
 232019/02/12 10:20:16 Starting server in http mode
 24```
 25
 26## API
 27
 28A HTTP jSON endpoint is available with the following possible fields: `method` `censusId`, `claimData`, `rootHash` and `proofData`.
 29
 30If `pubKey` has been configured for a specific `censusId`, then two more methods are available (`timeStamp` and `signature`) to provide authentication.
 31
 32The next table shows the available methods and its relation with the fields.
 33
 34| method     | censusId  | claimData | rootHash | proofData | protected? | description |
 35|------------|-----------|-----------|----------|-----------|------------|------------|
 36| `addClaim`   | mandatory | mandatory | none     | none      | yes | adds a new claim to the merkle tree       |
 37| `getRoot`    | mandatory | none      | none     | none      | no         | get the current merkletree root hash
 38| `genProof`   | mandatory | mandatory | optional | none      | no         | generate the merkle proof for a given claim
 39| `checkProof` | mandatory | mandatory | optional | mandatory | no         | check a claim and its merkle proof 
 40| `getIdx`     | mandatory | mandatory | optional | none      | no         | get the merkletree data index of a given claim
 41| `dump`       | mandatory | none      | optional | none      | yes        | list the contents of the census for a given hash
 42
 43
 44## Signature
 45
 46The signature provides authentication by signing a concatenation of the following strings (even if empty) without spaces: `method censusId rootHash claimData timeStamp`.
 47
 48The `timeStamp` when received on the server side must not differ more than 10 seconds from the current UNIX time.
 49
 50## Examples
 51
 52#### add claims
 53
 54Add two new claims, one for `Jon Snow` and another for `Tyrion`.
 55```
 56curl -d '{"method":"addClaim","censusID":"GoT_Favorite","claimData":"Jon Snow"}' http://localhost:1500
 57
 58{"error":false,"response":""}
 59```
 60
 61```
 62curl -d '{"method":"addClaim","censusID":"GoT_Favorite","claimData":"Tyrion"}' http://localhost:1500
 63
 64{"error":false,"response":""}
 65```
 66
 67In case signature is enabled:
 68
 69```
 70curl -d '{
 71"method":"addClaim",
 72"censusID":"GoT_Favorite",
 73"claimData":"Jon Snow", 
 74"timeStamp":"1547814675",
 75"signature":"a117c4ce12b29090884112ffe57e664f007e7ef142a1679996e2d34fd2b852fe76966e47932f1e9d3a54610d0f361383afe2d9aab096e15d136c236abb0a0d0e" }' http://localhost:1500
 76
 77{"error":false,"response":""}
 78```
 79
 80
 81#### generate proof
 82
 83Generate a merkle proof for the claim `Jon Snow`
 84
 85```
 86curl -d '{"method":"genProof","censusID":"GoT_Favorite","claimData":"Jon Snow"}' http://localhost:1500
 87
 88{"error":false,"response":"0x000200000000000000000000000000000000000000000000000000000000000212f8134039730791388a9bd0460f9fbd0757327212a64b3a2b0f0841ce561ee3"}
 89```
 90
 91If `rootHash` is specified, the proof will be calculated for the given root hash.
 92
 93#### get root
 94
 95The previous merkle proof is valid only for the current root hash. Let's get it
 96
 97```
 98curl -d '{"method":"getRoot","censusID":"GoT_Favorite"}' http://localhost:1500
 99
100{"error":false,"response":"0x2f0ddde5cb995eae23dc3b75a5c0333f1cc89b73f3a00b0fe71996fb90fef04b"}
101```
102
103
104#### check proof
105
106Now let's check if the proof is valid
107
108```
109curl -d '{
110"method":"checkProof",
111"censusID":"GoT_Favorite","claimData":"Jon Snow",
112"rootHash":"0x2f0ddde5cb995eae23dc3b75a5c0333f1cc89b73f3a00b0fe71996fb90fef04b",
113"proofData":"0x000200000000000000000000000000000000000000000000000000000000000212f8134039730791388a9bd0460f9fbd0757327212a64b3a2b0f0841ce561ee3"}' http://localhost:1500
114
115{"error":false,"response":"valid"}
116```
117
118If `rootHash` is not specified, the current root hash is used.
119
120#### dump
121
122Dump contents of a specific censusId (values)
123
124```
125curl -d '{"method":"dump","censusID":"GoT_Favorite"}' http://localhost:1500
126
127{"error":false,"response":"[\"Tyrion\",\"Jon Snow\"]"}
128```
129
130If `rootHash` is specified, dump will return the values for the merkle tree with the given root hash.