api.md

# Eris DB web APIs (draft)

### for eris-db version 0.11.x

Eris DB allows remote access to its functionality over http and websocket. It currently supports [JSON-RPC 2.0](http://www.jsonrpc.org/specification), and REST-like http. There is also javascript bindings available in the [erisdb-js](TODO) library.

## TOC

- [HTTP Requests](#http-requests)
- [JSON-RPC 2.0](#json-rpc)
- [REST-like HTTP](#rest-like)
- [Common objects and formatting](#formatting-conventions)
- [Event-system](#event-system)
- [Methods](#methods)
- [NameReg](#namereg)
- [Filters](#queries-filters)

<a name="http-requests"></a>
## HTTP Requests

The only data format supported is JSON. All post requests needs to use `Content-Type: application/json`. The charset flag is not supported (json is utf-8 encoded by default).

<a name="json-rpc"></a>
## JSON RPC 2.0

The default endpoints for JSON-RPC (2.0) is `/rpc` for http based, and `/socketrpc` for websocket. The namespace for the JSON-RPC service is `erisdb`.

It does not yet support notifications or batched requests.

### Objects

##### Errors

```
PARSE_ERROR      = -32700
INVALID_REQUEST  = -32600
METHOD_NOT_FOUND = -32601
INVALID_PARAMS   = -32602
INTERNAL_ERROR   = -32603
```

#####Request

```
{
	jsonrpc: <string>
	method:  <string>
	params:  <Object>
	id:      <string>
}
```

#####Response

```
{
	jsonrpc: <string>
	id:      <string>
	result:  <Object>
	error:   <Error>
}
```

#####Error

```
{
    code:    <number>
    message: <string>
}
```

Id can be any string value. Parameters are named, and wrapped in objects. Also, params, result and error params may be `null`.

#####Example

Request:

```
{
	jsonrpc: "2.0", 
	method: "erisdb.getAccount", 
	params: {address: "37236DF251AB70022B1DA351F08A20FB52443E37"}, 
	id="25"
}
```

Response:

```
{
    address: "37236DF251AB70022B1DA351F08A20FB52443E37",
    pub_key: null,
    sequence: 0,
    balance: 110000000000,
    code: "",
    storage_root: ""
}
```

<a name="rest-like"></a>
## REST-like HTTP

The REST-like API provides the typical endpoint structure i.e. endpoints are named as resources, parameters can be put in the path, and queries are used for filtering and such. It is not fully compatible with REST; partly because some GET requests can contain sizable input so POST is used instead. There are also some modeling issues but those will most likely be resolved before version 1.0.

<a name="formatting-conventions"></a>
##Common objects and formatting

This section contains some common objects and explanations of how they work.
  
###Numbers and strings

Numbers are always numbers, and never strings. This is different from Ethereum where currency values are so high they need string representations. The only thing hex strings are used for is to represent byte arrays. 

Hex strings are never prefixed.

#####Examples

```
"some_number_field" : 5892,
"another_number_field" : 0x52
"hex_string" : "37236DF251AB70022B1DA351F08A20FB52443E37"
```

###Keys and addresses

Public and Private keys in JSON data are either null, or on the form: `[type, hex]`, where `type` is the [public](https://github.com/tendermint/tendermint/blob/master/account/pub_key.go), or [private](https://github.com/tendermint/tendermint/blob/master/account/pub_key.go) key type, and `hex` is the hex-string representation of the key bytes.

- A `public address` is a 20 byte hex string.
- A `public key` is a 32 byte hex string.
- A `private key` is a 64 byte hex string.

#####WARNING

**When using a client-server setup, do NOT send public keys over non-secure connections. The only time this is fine is during development when the keys are nothing but test data and does not protect anything of value. Normally they should either be kept locally and used to sign transactions locally, held on the server where the blockchain client is running, or be passed over secure channels.**

#####Examples

A public address: `"37236DF251AB70022B1DA351F08A20FB52443E37"`

The corresponding Ed25519 public key: `[1, "CB3688B7561D488A2A4834E1AEE9398BEF94844D8BDBBCA980C11E3654A45906"]`

The corresponding Ed25519 private key: `[1, "6B72D45EB65F619F11CE580C8CAED9E0BADC774E9C9C334687A65DCBAD2C4151CB3688B7561D488A2A4834E1AEE9398BEF94844D8BDBBCA980C11E3654A45906"]`

<a name="the-transaction-types"></a>
###The transaction types

These are the types of transactions. Note that in DApp programming you would only use the `CallTx`, and maybe `NameTx`.

####SendTx

```
{
	inputs:  [<TxInput>]
	outputs: [<TxOutput>]
}
```

####CallTx

```
{
	input:     <TxInput>
	address:   <string>
	gas_limit: <number>
	fee:       <number>
	data:      <string>
}
```

####NameTx

```
{
	input:  <TxInput>
	name:   <string>
	data:   <string>
	amount: <number>
	fee:    <number>
}
```

####BondTx

```
{
	pub_key:   <PubKey>
	signature: <string>
	inputs:    [<TxInput>]
	unbond_to: [<TxOutput>]
}
```

####UnbondTx

```
{
	address:   <string>
	height:    <number>
	signature: <string>