Using HTTP(S) and REST to access Counterparty API

Just a heads up for those who use (or serve, or want to do either of those) the Counterparty API.

The Counterparty API has been available via REST (/rest) for a while now, but it’s relatively poorly documented and evangelized and I don’t know anyone who is using it. By now, however, most other often used documentation (including our JSON-RPC API and CLI) has been updated and fixed so the Counterparty REST API will soon get more attention.

Why use a RESTful API? Google has all the answers, so I’ll make it very simple and Counterparty-specific:

  • Works in the browser and uses HTTP(S), so it’s very easy to secure, serve and consume (imagine using a single wget command or URL to get asset issuance information).
  • Supports HTTPS for improved privacy (the provider can, but doesn’t have to, keep Web and API logs,but that’s no different from the current JSON-RPC)
  • Bitcoin Core’s RESTful API is improving, so although it’s not complete yet, with access to both Counterparty and Bitcoin Core RESTful API certain tasks can be accomplished completely via HTTPS. Remember that by default Bitcoin Core does not support JSON-RPC over SSL.
  • Better request logging

Because of these and other reasons it may be easier and cheaper to provide redundant Counterparty API endpoints and develop and serve applications.

###Example Request: Get Sends for an Address

Normally to serve this on the Web you’d change the port to 80 or 443 and remove authentication, but the default settings serve REST API on the usual port (here for testnet) and in this example require basic authentication:

http://rpc:1234@127.0.0.1:14000/rest/sends/get?source=mwTESt2VP3Q9M99GNWYvvaLQ1owrGTTjTb

The method used is get_{table} (here, get_sends), which you can read about in the Counterparty API documentation.

(By the way I noticed that the client’s Content-Headers must be set to application/json for this to work. I’ll have to see more about optimal server-side settings when counterparty-server is behind a proxy, etc.)

###Example Response

As expected, this method returns a list of rows from the sends table, and each contains information related to send actions from the specified address. It’s the same thing you’d get with JSON-RPC, of course, but in real life you’d use HTTPS over the port 80 or 443.

[{
	"asset": "XCP",
	"destination": "mr1vZMVLU3jDHZmzrXqM4q5V1QYtJft62U",
	"source": "mwTESt2VP3Q9M99GNWYvvaLQ1owrGTTjTb",
	"tx_hash": "d6ff5802e15d58913c850a2ef0fc4044a97306b5643d3825670aef85cb2e0c0d",
	"tx_index": 10617,
	"block_index": 1063971,
	"quantity": 2000000,
	"status": "valid"
}, {
	"asset": "UTFEIGHTTWO",
	"destination": "mrggywkshRFghJq2z3J5ihGdsabpcAHuth",
	"source": "mwTESt2VP3Q9M99GNWYvvaLQ1owrGTTjTb",
	"tx_hash": "d0c53fbffeeb047d29f8c264e663cee92b4445be2a3d005872c4af24ccfd786d",
	"tx_index": 10651,
	"block_index": 1082455,
	"quantity": 343,
	"status": "valid"
}, {
	"asset": "UTFEIGHTTWO",
	"destination": "mndnMzJuAqgHcGpCqBMH4Ehurb1FmnSzhA",
	"source": "mwTESt2VP3Q9M99GNWYvvaLQ1owrGTTjTb",
	"tx_hash": "b0db4e92c1f9b3b9413e24b28dedea0bf317469a61b319b895974bf095c1cf3e",
	"tx_index": 10652,
	"block_index": 1082490,
	"quantity": 343,
	"status": "valid"
}]

###API LOG

If API log is enabled in counterparty-server, it’s easier to watch requests, troubleshoot issues and analyze or tune your server performance.

127.0.0.1 - - [15/Jan/2017 16:30:21] "GET /rest/sends/get?source=mwTESt2VP3Q9M99GNWYvvaLQ1owrGTTjTb HTTP/1.1" 200

The RESTful API interface documentation will be improved in the official docs in coming weeks.