From 92575b6090b6bfaeea3142b8feb576e9038401ab Mon Sep 17 00:00:00 2001 From: Marco Stronati Date: Fri, 13 Jul 2018 14:04:23 +0200 Subject: [PATCH] Doc: move rpc_usage to tutorials/rpc --- docs/Makefile | 4 +- docs/api/rpc_usage.rst.inc | 33 ----------------- docs/doc_gen/rpc_doc.ml | 10 +---- docs/tutorials/rpc.rst | 76 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 79 insertions(+), 44 deletions(-) delete mode 100644 docs/api/rpc_usage.rst.inc create mode 100644 docs/tutorials/rpc.rst diff --git a/docs/Makefile b/docs/Makefile index c1f49dab8..52b3d0328 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -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 diff --git a/docs/api/rpc_usage.rst.inc b/docs/api/rpc_usage.rst.inc deleted file mode 100644 index 5ed479f38..000000000 --- a/docs/api/rpc_usage.rst.inc +++ /dev/null @@ -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`. - -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) ``. - -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//proto/context/contracts//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 with ``. 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 ``. - -Of course, you can use your standard HTTP tool or library as well to -perform all these tasks. diff --git a/docs/doc_gen/rpc_doc.ml b/docs/doc_gen/rpc_doc.ml index 99038248a..81e6b8b2d 100644 --- a/docs/doc_gen/rpc_doc.ml +++ b/docs/doc_gen/rpc_doc.ml @@ -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) -> diff --git a/docs/tutorials/rpc.rst b/docs/tutorials/rpc.rst new file mode 100644 index 000000000..1a0d28b7d --- /dev/null +++ b/docs/tutorials/rpc.rst @@ -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 ` of RPC calls is also available. +The changes made in June 2018 for pre-Betanet are recapitulated in +:ref:`this page`. + + +The general call of an RPC from the client is ``tezos-admin-client rpc +(get|post) ``. +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//proto/context/contracts//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 with ``. 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 `_.