Doc: reference endpoints using :http: (#3362)

doc/build_apps/example.rst

@@ -9,7 +9,7 @@ The repository contains a C++ implementation of a simple example application for
 
 The Logging application implements a trivial protocol, made up of four transaction types:
 
-- ``POST /app/log/private``, which writes a private log message at a given index. Note that the log message will be encrypted on the ledger and only readable by nodes on the network.
+- :http:POST:`/log/private`, which writes a private log message at a given index. Note that the log message will be encrypted on the ledger and only readable by nodes on the network.
 
     Log a private message:
 
@@ -20,7 +20,7 @@ The Logging application implements a trivial protocol, made up of four transacti
             "msg": "A sample private log message"
         }
 
-- ``GET /app/log/private``, which retrieves a private log message from a given index written by a previous ``POST /app/log/private`` call.
+- :http:GET:`/log/private`, which retrieves a private log message from a given index written by a previous :http:POST:`/log/private` call.
 
     Get a private message:
 
@@ -30,7 +30,7 @@ The Logging application implements a trivial protocol, made up of four transacti
             "id": 42
         }
 
-- ``POST /app/log/public``, which writes a public log message at a given index. Note that the log message will be not be encrypted and thus to anyone with access to the ledger.
+- :http:POST:`/log/public`, which writes a public log message at a given index. Note that the log message will be not be encrypted and thus to anyone with access to the ledger.
 
     Log a public message:
 
@@ -41,7 +41,7 @@ The Logging application implements a trivial protocol, made up of four transacti
             "msg": "A sample public log message"
         }
 
-- ``GET /app/log/public``, which retrieves a public public log from a given index written by a previous ``POST /app/log/public`` call.
+- :http:GET:`/log/public`, which retrieves a public public log from a given index written by a previous :http:POST:`/log/public` call.
 
     Get a public message:
 

doc/build_apps/js_app_bundle.rst

@@ -74,14 +74,14 @@ Each endpoint object contains the following information:
   the ``js_module``.
 - ``"authn_policies"``: A list of :ref:`authentication policies <build_apps/auth/index:User Authentication>` to be applied before the endpoint
   is executed. An empty list indicates an unauthenticated endpoint which can be called by anyone. Possible entries are:
-  
+
   - ``"user_cert"``
   - ``"user_signature"``
   - ``"member_cert"``
   - ``"member_signature"``
   - ``"jwt"``
   - ``"no_auth"``
-  
+
 - ``"forwarding_required"``: A string indicating whether the endpoint is always forwarded, or whether it is safe to sometimes execute on followers. Possible values are:
 
   - ``"always"``
@@ -94,7 +94,7 @@ Each endpoint object contains the following information:
   - ``"readonly"``
   - ``"historical"``
 
-- ``"openapi"``:  An `OpenAPI Operation Object <https://swagger.io/specification/#operation-object>`_ 
+- ``"openapi"``:  An `OpenAPI Operation Object <https://swagger.io/specification/#operation-object>`_
   without `references <https://swagger.io/specification/#reference-object>`_. This is descriptive but not
   enforced - it will be inserted into the generated OpenAPI document for this service, but will not restrict the
   types of the endpoint's requests or responses.
@@ -155,4 +155,4 @@ If CCF is updated and introduces a newer JavaScript engine version, then any pre
     SUCCESS | Writing proposal to ./refresh_js_app_bytecode_cache_proposal.json
     SUCCESS | Wrote vote to ./refresh_js_app_bytecode_cache_vote_for.json
 
-.. note:: The operator RPC ``/node/js_metrics`` returns the size of the bytecode and whether it is used. If it is not used, then either no bytecode is stored or it needs to be re-compiled due to a CCF update.
+.. note:: The operator RPC :http:GET:`/js_metrics` returns the size of the bytecode and whether it is used. If it is not used, then either no bytecode is stored or it needs to be re-compiled due to a CCF update.

doc/build_apps/logging_cpp.rst

@@ -73,9 +73,9 @@ Each function is installed as the handler for a specific HTTP resource, defined
     :end-before: SNIPPET_END: install_record
     :dedent:
 
-This example installs at ``"log/private", HTTP_POST``, so will be invoked for HTTP requests beginning ``POST /app/log/private``.
+This example installs at ``"log/private", HTTP_POST``, so will be invoked for HTTP requests beginning :http:POST:`/log/private`.
 
-The return value from ``make_endpoint`` is an ``Endpoint&`` object which can be used to alter how the handler is executed. For example, the handler for ``/log/private`` shown above sets a `schema` declaring the types of its request and response bodies. These will be used in calls to the ``/api`` endpoint to populate the relevant parts of the OpenAPI document. There are other endpoints installed for the URI path ``/log/private`` with different verbs, to handle ``GET`` and ``DELETE`` requests. Any other verbs, without an installed endpoint, will not be accepted - the framework will return a ``405 Method Not Allowed`` response.
+The return value from ``make_endpoint`` is an ``Endpoint&`` object which can be used to alter how the handler is executed. For example, the handler for :http:POST:`/log/private` shown above sets a `schema` declaring the types of its request and response bodies. These will be used in calls to the ``/api`` endpoint to populate the relevant parts of the OpenAPI document. There are other endpoints installed for the URI path ``/log/private`` with different verbs, to handle ``GET`` and ``DELETE`` requests. Any other verbs, without an installed endpoint, will not be accepted - the framework will return a ``405 Method Not Allowed`` response.
 
 To process the raw body directly, a handler should use the general lambda signature which takes a single ``EndpointContext&`` parameter. Examples of this are also included in the logging sample app. For instance the ``log_record_text`` handler takes a raw string as the request body:
 

doc/governance/accept_recovery.rst

@@ -55,7 +55,7 @@ To restore private transactions and complete the recovery procedure, recovery me
 
 .. note:: The recovery members who submit their recovery shares do not necessarily have to be the members who previously accepted the recovery.
 
-Member recovery shares are stored in the ledger, encrypted with each member's public encryption key. Members can retrieve their encrypted recovery shares from the public-only service via the ``GET /gov/recovery_share`` endpoint, perform the share decryption securely (see for example :doc:`hsm_keys`) and submit the decrypted recovery share via the ``POST /gov/recovery_share`` endpoint.
+Member recovery shares are stored in the ledger, encrypted with each member's public encryption key. Members can retrieve their encrypted recovery shares from the public-only service via the :http:GET:`/recovery_share` endpoint, perform the share decryption securely (see for example :doc:`hsm_keys`) and submit the decrypted recovery share via the :http:POST:`/recovery_share` endpoint.
 
 The recovery share retrieval, decryption and submission steps can be conveniently performed in one step using the ``submit_recovery_share.sh`` script:
 
@@ -75,7 +75,7 @@ The recovery share retrieval, decryption and submission steps can be convenientl
     x-ms-ccf-transaction-id: 4.30
     2/2 recovery shares successfully submitted. End of recovery procedure initiated.
 
-When the recovery threshold is reached, the ``POST /gov/recovery_share`` endpoint signals that the end of the recovery procedure is initiated and the that private ledger is now being recovered. Operators and members can monitor the progress of the private recovery process via the ``GET /node/state`` endpoint.
+When the recovery threshold is reached, the :http:POST:`/recovery_share` endpoint signals that the end of the recovery procedure is initiated and the that private ledger is now being recovered. Operators and members can monitor the progress of the private recovery process via the :http:GET:`/state` endpoint.
 
 .. note:: While all nodes are recovering the private ledger, no new transaction can be executed by the network.
 

doc/operations/certificates.rst

@@ -43,4 +43,4 @@ The procedure that operators and members should follow is summarised in the foll
 
     section Node 3
     Initial Validity Period (24h default)      : done, 01-03/00:00, 1d
-    New Joiner Validity Period                 : 01-03/15:00, 4d
+    New Joiner Validity Period                 : 01-03/15:00, 4d

doc/operations/recovery.rst

@@ -22,7 +22,7 @@ To initiate the first phase of the recovery procedure, one or several nodes shou
 
     $ cchost --config /path/to/config/file
 
-Each node will then immediately restore the public entries of its ledger ("ledger.directory`` and ``ledger.read_only_ledger_dir`` configuration entries). Because deserialising the public entries present in the ledger may take some time, operators can query the progress of the public recovery by calling ``GET /node/state`` which returns the version of the last signed recovered ledger entry. Once the public ledger is fully recovered, the recovered node automatically becomes part of the public network, allowing other nodes to join the network.
+Each node will then immediately restore the public entries of its ledger ("ledger.directory`` and ``ledger.read_only_ledger_dir`` configuration entries). Because deserialising the public entries present in the ledger may take some time, operators can query the progress of the public recovery by calling :http:GET:`/state` which returns the version of the last signed recovered ledger entry. Once the public ledger is fully recovered, the recovered node automatically becomes part of the public network, allowing other nodes to join the network.
 
 The recovery procedure can be accelerated by specifying a valid snapshot file created by the previous service in the directory specified via the ``snapshots.directory`` configuration entry. If specified, the ``recover`` node will automatically recover the snapshot and the ledger entries following that snapshot, which in practice should be a fraction of the total time required to recover the entire historical ledger.`
 
@@ -37,7 +37,7 @@ The state machine for the ``recover`` node is as follows:
         PartOfPublicNetwork-- member shares reassembly -->ReadingPrivateLedger;
         ReadingPrivateLedger-->PartOfNetwork;
 
-.. note:: It is possible that the length of the ledgers of each node may differ slightly since some transactions may not have yet been fully replicated. It is preferable to use the ledger of the primary node before the service crashed. If the latest primary node of the defunct service is not known, it is recommended to `concurrently` start as many nodes as previous existed in ``recover`` mode, each recovering one ledger of each defunct node. Once all nodes have completed the public recovery procedure, operators can query the highest recovered signed seqno (as per the response to the ``GET /node/state`` endpoint) and select this ledger to recover the service. Other nodes should be shutdown and new nodes restarted with the ``join`` option.
+.. note:: It is possible that the length of the ledgers of each node may differ slightly since some transactions may not have yet been fully replicated. It is preferable to use the ledger of the primary node before the service crashed. If the latest primary node of the defunct service is not known, it is recommended to `concurrently` start as many nodes as previous existed in ``recover`` mode, each recovering one ledger of each defunct node. Once all nodes have completed the public recovery procedure, operators can query the highest recovered signed seqno (as per the response to the :http:GET:`/state` endpoint) and select this ledger to recover the service. Other nodes should be shutdown and new nodes restarted with the ``join`` option.
 
 Similarly to the normal join protocol (see :ref:`operations/start_network:Adding a New Node to the Network`), other nodes are then able to join the network.
 

doc/use_apps/verify_quote.rst

@@ -13,7 +13,7 @@ A client can verify the validity of the SGX quote of the CCF node that it connec
 
 The script verifies the target CCF node's SGX quote by:
 
-1. Retrieving the node's SGX quote via the ``/node/quote`` endpoint.
+1. Retrieving the node's SGX quote via the :http:GET:`/quotes/self` endpoint.
 2. Verifying that the cryptographic hash of the node's identity public key (as presented in the node's certificate in the TLS session) matches the quote's report data.
 3. Verifying that the quote's measurement (``MRENCLAVE``) matches one of the trusted enclave measurements.
 
@@ -26,11 +26,11 @@ A specific trusted SGX enclave measurement can be specified ``--mrenclave <mrenc
     mrenclave: 3175971c02d00c1a8f9dd23ca89e64955c5caa94e24f4a3a0579dcfb2e6aebf9
     Quote verification successful.
 
-If no code measurement is specified, the ``verify_quote.sh`` script automatically verifies it against the code versions currently trusted by the CCF service, as returned by the ``/node/code`` endpoint.
+If no code measurement is specified, the ``verify_quote.sh`` script automatically verifies it against the code versions currently trusted by the CCF service, as returned by the :http:GET:`/code` endpoint.
 
 .. note:: The ``verify_quote.sh`` script uses the ``oeverify`` CLI included in the Open Enclave ``hostverify`` package available on the `Open Enclave release page <https://github.com/openenclave/openenclave/releases>`_.
 
-Alternatively, the SGX quotes of all currently trusted nodes can be retrieved via the ``/node/quotes`` endpoint:
+Alternatively, the SGX quotes of all currently trusted nodes can be retrieved via the :http:GET:`/quotes` endpoint:
 
 .. code-block:: bash
 

doc/use_apps/verify_tx.rst

@@ -8,7 +8,7 @@ Checking for Commit
 
 Because of the decentralised nature of CCF, a request is committed to the ledger only once a number of nodes have agreed on that request.
 
-To guarantee that their request is successfully committed to the ledger, a user should issue a ``GET /tx`` request, specifying the version received in the response. This version is constructed from a view and a sequence number.
+To guarantee that their request is successfully committed to the ledger, a user should issue a :http:GET:`/tx` request, specifying the version received in the response. This version is constructed from a view and a sequence number.
 
 .. code-block:: bash
 
@@ -22,7 +22,7 @@ To guarantee that their request is successfully committed to the ledger, a user
 
 This example queries the status of transaction ID ``2.18`` (constructed from view ``2`` and sequence number ``18``). The response indicates this was successfully committed. The headers also show that the service has since made progress with other requests and changed view (``x-ms-ccf-transaction-id: 5.42``).
 
-The possible statuses returned by ``GET /tx`` are:
+The possible statuses returned by :http:GET:`/tx` are:
 
 - ``UNKNOWN`` - this node has not received a transaction with the given ID
 - ``PENDING`` - this node has received a transaction with the given ID, but does not yet know if the transaction has been committed
@@ -56,7 +56,7 @@ This means that the request may return ``202 Accepted`` at first, with a suggest
 .. code-block:: bash
 
     $ curl -X GET "https://<ccf-node-address>/app/receipt?transaction_id=2.23" --cacert networkcert.pem --key user0_privk.pem --cert user0_cert.pem
-    
+
     {'leaf': 'fdc977c49d3a8bdf986176984e9432a09b5f6fe0c04e0b1c2dd177c03fdca9ec',
      'node_id': '682c161e1bc0aec694cac58a6ea456e1caa6c9c56d8dd873da9455c341947065',
      'proof': [{'left': 'f847e5efe3965b0dacb5c15c666602807a11fdecd465d0976779eed27121ffa3'},
@@ -73,7 +73,7 @@ Note that receipts over signature transactions are a special case, for example:
 .. code-block:: bash
 
     $ curl -X GET "https://<ccf-node-address>/app/receipt?transaction_id=2.35" --cacert networkcert.pem --key user0_privk.pem --cert user0_cert.pem
-    
+
     {'leaf': 'fdc977c49d3a8bdf986176984e9432a09b5f6fe0c04e0b1c2dd177c03fdca9ec',
      'node_id': '06fef62c80b6471c7005c1b114166fd1b0e077845f5ad544ad4eea4fb1d31f78',
      'proof': [],