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, and REST-like http. There is also javascript bindings available in the erisdb-js library.

TOC

• HTTP Requests
• JSON-RPC 2.0
• REST-like HTTP
• Common objects and formatting
• Event-system
• Methods
• NameReg
• Filters

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).

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: ""
}

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.