balsoft/ligo
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Doc: move rpc_usage to tutorials/rpc

Browse Source
This commit is contained in:
Marco Stronati 2018-07-13 14:04:23 +02:00
parent c7cfdcb4d9
commit 92575b6090
4 changed files with 79 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/Makefile
View File

@ -24,8 +24,8 @@ api/errors.rst: $(DOCERRORDIR)/error_doc.ml
$(DOCGENDIR)/rpc_doc.exe:
@cd .. && dune build docs/$(DOCGENDIR)/rpc_doc.exe
api/rpc.rst: $(DOCGENDIR)/rpc_doc.exe api/rpc_usage.rst.inc
@dune exec $(DOCGENDIR)/rpc_doc.exe < api/rpc_usage.rst.inc > api/rpc.rst
api/rpc.rst: $(DOCGENDIR)/rpc_doc.exe
@dune exec $(DOCGENDIR)/rpc_doc.exe > api/rpc.rst
$(DOCGENDIR)/p2p_doc.exe:
@cd .. && dune build docs/$(DOCGENDIR)/p2p_doc.exe

33
docs/api/rpc_usage.rst.inc
View File

@ -1,33 +0,0 @@
This document contains the list of RPC services provided by the Tezos
node. It is generated from the OCaml source code (master branch).
The changes made in June 2018 for pre-Betanet are recapitulated in
:ref:`this page<rpc_changes_june_2018>`.
Usage
*****
In order to interact with a Tezos node, you may use RPC calls through the
client using this command ``tezos-admin-client rpc (get|post) <url>``.
For instance, if you wish to request the current balance of a given
block and contract, you can call the associated RPC via the command :
``$ tezos-admin-client rpc get
/blocks/<block_id>/proto/context/contracts/<contract_id>/balance``.
A RPC may takes an *input* and generates an *output* both in JSON
format. For example, the previous RPC call, that does not require an
input, would display on the standard output : ``{ "balance":
"4000000000000" }``. When calling a RPC that requires an input
through command-line, you will be prompted to provide the JSON input
in your default configured text editor. Alternatively, you can provide
the JSON input using command
``$ tezos-admin-client rpc post <url> with <JSON>``. Don't forget to quote
the JSON according to your shell rules.
You can also obtain the list of RPCs on the command line with
``tezos-admin-client rpc list /``, and the description of each service
using ``tezos-admin-client rpc format <url>``.
Of course, you can use your standard HTTP tool or library as well to
perform all these tasks.

10
docs/doc_gen/rpc_doc.ml
View File

@ -267,18 +267,10 @@ let pp_document ppf descriptions =
Format.fprintf ppf "%a@." Rst.pp_raw_html Rst.style ;
(* Script : hack *)
Format.fprintf ppf "%a@." Rst.pp_raw_html Rst.script ;
(* Page title *)
Format.fprintf ppf "%a" Rst.pp_h1 "RPC API" ;
(* include/copy usage.rst from input *)
let rec loop () =
let s = read_line () in
Format.fprintf ppf "%s@\n" s ;
loop () in
begin try loop () with End_of_file -> () end ;
Format.fprintf ppf "@\n" ;
(* Index *)
Format.pp_set_margin ppf 10000 ;
Format.pp_set_max_indent ppf 9000 ;
Format.fprintf ppf "%a" Rst.pp_ref "rpc_index" ;
Rst.pp_h2 ppf "RPCs - Index" ;
List.iter
(fun (name, prefix, rpc_dir) ->

76
docs/tutorials/rpc.rst Normal file
View File

@ -0,0 +1,76 @@
.. _rpc:
JSON/RPC interface
==================
The Tezos node provides a JSON/RPC interface. Note that it is an RPC,
and it is JSON based, but it does not follow the “JSON-RPC” protocol. It
is not active by default and it must be explicitly activated with the
``--rpc-addr`` option. Typically, if you are not trying to run a local
network and just want to explore the RPC, you would run:
::
./tezos-node run --rpc-addr localhost
The RPC interface is self-documented and the ``tezos-client`` executable
is able to pretty-print the RPC API. For instance, to see the API
provided by the Tezos Shell:
::
./tezos-client rpc list
To get API attached to the “genesis” block, including the remote
procedures provided by the associated economic protocol version:
::
./tezos-client rpc list /blocks/genesis/
You might also want the JSON schema describing the expected input and
output of a RPC. For instance:
::
./tezos-client rpc schema /blocks/genesis/hash
Note: you can get the same information, but as a raw JSON object, with a
simple HTTP request:
::
curl -s localhost:8732/chains/main/blocks/head~10
wget --post-data '{ "recursive": true }' -O - http://localhost:8732/describe
wget --post-data '{ "recursive": true }' -O - http://localhost:8732/describe/blocks/genesis
wget -O - http://localhost:8732/describe/blocks/genesis/hash
An online :ref:`index <rpc_index>` of RPC calls is also available.
The changes made in June 2018 for pre-Betanet are recapitulated in
:ref:`this page<rpc_changes_june_2018>`.
The general call of an RPC from the client is ``tezos-admin-client rpc
(get|post) <url>``.
For instance, if you wish to request the current balance of a given
block and contract, you can call the associated RPC via the command :
``$ tezos-admin-client rpc get
/blocks/<block_id>/proto/context/contracts/<contract_id>/balance``.
A RPC may take an *input* and generates an *output* both in JSON
format. For example, the previous RPC call, that does not require an
input, would display on the standard output : ``{ "balance":
"4000000000000" }``. When calling a RPC that requires an input
through command-line, you will be prompted to provide the JSON input
in your default configured text editor. Alternatively, you can provide
the JSON input using command
``$ tezos-admin-client rpc post <url> with <JSON>``. Don't forget to quote
the JSON according to your shell rules.
If you want to learn more about the exchange of RPCs between node and
client you can pass the option `-l` and the client will print all the
calls with their input/output.
A useful util to manipulate JSON is `jq <https://stedolan.github.io/jq/>`_.