-
Notifications
You must be signed in to change notification settings - Fork 94
API_Specification
All messages are encoded as JSON objects. There are three types of messages:
- requests
- responses
- events
Requests are sent by clients to issue commands, obtain state information, and subscribe to events.
Requests are comprised of the following fields:
- method - the name of the command to execute
- params - an array containing the parameters
- id - an optional arbitrary data field used by client to identify the request
The params field may be omitted for commands that do not take parameters.
Examples:
- {"method": "getvaultinfo"}
- {"method": "getaccountinfo", "params": ["foo"], "id": 1}
Responses are sent by the CoinVault daemon to clients to acknowledge receipt and execution of commands, provide requested state data, and report errors.
Responses are comprised of the following fields:
- result - an object containing an acknowledgement of command execution and/or requested data (null if execution failed)
- error - an object containing error information (null if request was successful)
- message - a human-readable message describing the error
- code - a numeric error code
- id - echo of client-provided id (null if no id provided)
For all responses, either error is null or result is null but never both.
Events are sent by the CoinVault daemon to clients to inform of state changes.
Events are comprised of the following fields:
- event - a string denoting the type of event
- data - all data for event
####Event Types
- txinserted - a new transaction has been inserted into the vault
- txstatuschanged - an existing transaction's status has changed
- merkleblockinserted - a new merkle block has been inserted into the vault
Examples:
- {"event": "txinserted", "data": {"hash": "64f570...", "status": "propagated", ...}}
- {"event": "merkleblockinserted", "data": {"hash": "0000000000e187...", "height": 257954, ...}}
The HTTP REST API provides a stateless protocol for remote command execution. In addition, a callback URL may be provided to receive events.
The CoinVault daemon must be configured to listen for requests on a particular port. This is specified by setting the httpport variable in the config file.
Clients must provide appropriate authentication fields in the HTTP header.
The message body consists solely of a plaintext JSON-encoded request.
The WebSockets API provides full-duplex connections allowing multiple commands to be issued asynchronously to the CoinVault daemon without needing to establish a new connection for each command. It also allows the CoinSocket daemon to send events to clients using the same connection.
A javascript client library is provided to allow application developers to quickly integrate their browser-based or node-based applications with CoinVault.
The CoinSocket daemon must be configured to listen for requests on a particular port. This is specified by setting the wsport variable in the config file.