Difference between revisions of "NodeCore HTTP API"

From Veriblock Wiki
Jump to: navigation, search
(Created page with "See: Developer_Guide == Overview == NodeCore v0.4.5 introduces an HTTP API to supplement the existing gRPC Admin API. All methods currently available in the gRPC API are...")
 
 
(15 intermediate revisions by 4 users not shown)
Line 1: Line 1:
See: [[Developer_Guide]]
+
See: [[Developer_Guide]], [[GRPC]], [[API]]
  
 
== Overview ==
 
== Overview ==
  
 
NodeCore v0.4.5 introduces an HTTP API to supplement the existing gRPC Admin API. All methods currently available in the gRPC API are also available in the HTTP API.
 
NodeCore v0.4.5 introduces an HTTP API to supplement the existing gRPC Admin API. All methods currently available in the gRPC API are also available in the HTTP API.
 +
 +
Full API spec:
 +
 +
* https://resources.veriblock.org/Html_Protocol_Spec_0.4.6.html
  
 
== Usage ==
 
== Usage ==
Line 11: Line 15:
 
The API follows the [https://www.jsonrpc.org/specification JSON-RPC 2.0 Specification]. All API requests are made to [http://localhost:10600/api http://localhost:10600/api]. Both request and response will use the '''application/json''' content type.
 
The API follows the [https://www.jsonrpc.org/specification JSON-RPC 2.0 Specification]. All API requests are made to [http://localhost:10600/api http://localhost:10600/api]. Both request and response will use the '''application/json''' content type.
  
=== Making a Request ===a
+
=== Making a Request ===
  
 
In accordance with the JSON-RPC specification, there is a standard request object format:
 
In accordance with the JSON-RPC specification, there is a standard request object format:
Line 26: Line 30:
 
* '''params''': The RPC method-specific request parameters. The internal API documentation describes the request objects for each method.
 
* '''params''': The RPC method-specific request parameters. The internal API documentation describes the request objects for each method.
 
* '''id''': A string or number determined by the client to uniquely identify the request. This same id will be used in the response.
 
* '''id''': A string or number determined by the client to uniquely identify the request. This same id will be used in the response.
 +
 +
Example getinfo
 +
 +
<pre>{
 +
"jsonrpc": "2.0",
 +
"method": "getinfo",
 +
"params": {},
 +
"id": 1
 +
}</pre>
 +
 +
Example getblocks
 +
 +
<pre>{
 +
"jsonrpc": "2.0",
 +
"method": "getblocks",
 +
"params": {
 +
"searchLength": 2000,
 +
"filters": [{index: 349601}]
 +
}</pre>
  
 
=== Responses ===
 
=== Responses ===
Line 40: Line 63:
 
* '''result''': The RPC method-specific response object. The internal API documentation describes the response objects for each method.
 
* '''result''': The RPC method-specific response object. The internal API documentation describes the response objects for each method.
 
* '''id''': The exact string or number supplied by the client in the request object.
 
* '''id''': The exact string or number supplied by the client in the request object.
 +
 +
=== Making a Request with curl ===
 +
 +
==== getinfo ====
 +
 +
<pre>
 +
curl -H "Content-Type: application/json" --data '{"jsonrpc": "2.0", "method": "getinfo", "params": {}, "id": 1}' http://127.0.0.1:10600/api
 +
</pre>
 +
 +
==== getbalance ====
 +
 +
Note: balance is in Atomic Units, so divide by 100000000 to get amount in VBK.
 +
 +
<pre>
 +
curl -H "Content-Type: application/json" --data '{"jsonrpc": "2.0", "method": "getbalance", "params": {"addresses": ["V3TCJ69TfVVELGJi9H5c2m3smAiWeP"]}, "id": 1}' http://127.0.0.1:10600/api
 +
</pre>
 +
 +
==== getblockfromindex ====
 +
 +
<pre>
 +
curl -H "Content-Type: application/json" --data '{"jsonrpc": "2.0", "method": "getblocks", "params": {"searchLength": 1, "filters": [{ "index": "80000" }]}, "id": 1}' http://127.0.0.1:10600/api
 +
</pre>
 +
 +
==== sendcoins ====
 +
 +
Note: amount is in Atomic Units, so multiply by 100000000 to send VBK amount.
 +
 +
<pre>
 +
curl -H "Content-Type: application/json" --data '{"jsonrpc": "2.0", "method": "sendcoins", "params": {"sourceAddress": "V3TCJ69TfVVELGJi9H5c2m3smAiWeP","amounts": [{"address": "VBasFp1K8LvMWypcC6jFff3TW2JyTn","amount": 10000000}]}, "id": 1}' http://127.0.0.1:10600/api
 +
</pre>
 +
 +
==== gettransactions ====
 +
 +
<pre>
 +
curl -H "Content-Type: application/json" --data '{"jsonrpc": "2.0", "method": "gettransactions", "params": {"searchLength": 0, "ids": ["D634C6E7D7E19F083068DAB4ED9499EE312EF4ADACCCD74B496F4DE22ED527DC"]}, "id": 1}' http://127.0.0.1:10600/api
 +
</pre>
  
 
=== Configuration ===
 
=== Configuration ===
Line 51: Line 110:
  
 
If the '''rpc.security.password.enabled''' property in the ''nodecore.properties'' file is set to to '''true''', requests to the HTTP API will require the additional header '''X-VBK-RPC-PASSWORD''' to be set. The value of this header corresponds to the password defined in the property '''rpc.security.password''' in ''nodecore.properties''.
 
If the '''rpc.security.password.enabled''' property in the ''nodecore.properties'' file is set to to '''true''', requests to the HTTP API will require the additional header '''X-VBK-RPC-PASSWORD''' to be set. The value of this header corresponds to the password defined in the property '''rpc.security.password''' in ''nodecore.properties''.
 +
 +
 +
Example:
 +
 +
<code>--header "X-VBK-RPC-PASSWORD: your-password"</code>

Latest revision as of 20:29, 7 February 2022

See: Developer_Guide, GRPC, API

Overview

NodeCore v0.4.5 introduces an HTTP API to supplement the existing gRPC Admin API. All methods currently available in the gRPC API are also available in the HTTP API.

Full API spec:

Usage

By default, the HTTP API is bound to 127.0.0.1:10600. Assuming the defaults are left as is, documentation of the API methods and request/response types can be found at http://localhost:10600/api/docs.

The API follows the JSON-RPC 2.0 Specification. All API requests are made to http://localhost:10600/api. Both request and response will use the application/json content type.

Making a Request

In accordance with the JSON-RPC specification, there is a standard request object format:

{
	"jsonrpc": "2.0",
	"method": "getblocks",
	"params": {...},
	"id": 1
}
  • jsonrpc: Always "2.0" value
  • method: The RPC method name to invoke. Reference the internal API documentation at http://localhost:10600/api/docs#core.Admin for the list of methods available.
  • params: The RPC method-specific request parameters. The internal API documentation describes the request objects for each method.
  • id: A string or number determined by the client to uniquely identify the request. This same id will be used in the response.

Example getinfo

{
 "jsonrpc": "2.0",
 "method": "getinfo",
 "params": {},
 "id": 1
}

Example getblocks

{
 "jsonrpc": "2.0",
 "method": "getblocks",
 "params": {
 "searchLength": 2000,
 "filters": [{index: 349601}]
}

Responses

The standard response object format:

{
    "jsonrpc": "2.0",
    "result": {...},
    "id": 1
}
  • jsonrpc: Always "2.0" value
  • result: The RPC method-specific response object. The internal API documentation describes the response objects for each method.
  • id: The exact string or number supplied by the client in the request object.

Making a Request with curl

getinfo

curl -H "Content-Type: application/json" --data '{"jsonrpc": "2.0", "method": "getinfo", "params": {}, "id": 1}' http://127.0.0.1:10600/api

getbalance

Note: balance is in Atomic Units, so divide by 100000000 to get amount in VBK.

curl -H "Content-Type: application/json" --data '{"jsonrpc": "2.0", "method": "getbalance", "params": {"addresses": ["V3TCJ69TfVVELGJi9H5c2m3smAiWeP"]}, "id": 1}' http://127.0.0.1:10600/api

getblockfromindex

curl -H "Content-Type: application/json" --data '{"jsonrpc": "2.0", "method": "getblocks", "params": {"searchLength": 1, "filters": [{ "index": "80000" }]}, "id": 1}' http://127.0.0.1:10600/api

sendcoins

Note: amount is in Atomic Units, so multiply by 100000000 to send VBK amount.

curl -H "Content-Type: application/json" --data '{"jsonrpc": "2.0", "method": "sendcoins", "params": {"sourceAddress": "V3TCJ69TfVVELGJi9H5c2m3smAiWeP","amounts": [{"address": "VBasFp1K8LvMWypcC6jFff3TW2JyTn","amount": 10000000}]}, "id": 1}' http://127.0.0.1:10600/api

gettransactions

curl -H "Content-Type: application/json" --data '{"jsonrpc": "2.0", "method": "gettransactions", "params": {"searchLength": 0, "ids": ["D634C6E7D7E19F083068DAB4ED9499EE312EF4ADACCCD74B496F4DE22ED527DC"]}, "id": 1}' http://127.0.0.1:10600/api

Configuration

The IP address and port to which the HTTP API is bound can be configured by modifying the nodecore.properties file. The default values are:

http.api.bind.address = 127.0.0.1
http.api.bind.port = 10600

Security

If the rpc.security.password.enabled property in the nodecore.properties file is set to to true, requests to the HTTP API will require the additional header X-VBK-RPC-PASSWORD to be set. The value of this header corresponds to the password defined in the property rpc.security.password in nodecore.properties.


Example:

--header "X-VBK-RPC-PASSWORD: your-password"