Flesh out the rbt api-get documentation.
This updates the `rbt api-get` documentation to go into more detail on
the way the command works, showing examples for relative paths, absolute
URLs, and using options for query arguments.
Testing Done:
Built the docs. Checked for build errors, spelling errors, and link errors.
Reviewed at
api-get
=======
-:command:`rbt api-get` will request the API resource found at the provided
-``<path>`` and display it as JSON.
+:command:`rbt api-get` is a convenient way of fetching information from the
+Review Board API using HTTP GET. It takes a full URL or a path relative to the
+API, along with optional parameters for query arguments, and outputs the API
+payload as JSON.
+
+.. rbt-command-usage::
+
+
+Querying the API
+================
Paths will be appended to the root of the API to generate a URL. For example,
-the ``/review-requests/123/`` path would result in a request to
-``http://example.com/api/review-requests/123/``.
+if the Review Board server is located at ``https://example.com/``, the path
+``/review-requests/123/`` path would result in an HTTP GET request to
+``https://example.com/api/review-requests/123/``.
+
+For example:
+
+.. code-block:: console
-The path may also be replaced by a full URL. If :command:`rbt api-get`
-detects the path begins with ``http://`` or ``https://``, it will treat the
-path itself as the request URL.
+ $ rbt api-get /review-requests/
+ {
+ ...
+ }
-Query arguments may also be specified for the request. Each query argument
-takes the form of ``--<query-arg>=<value>``. For example::
+The full URL to an API endpoint can be provided instead. For example:
+
+.. code-block:: console
+
+ $ rbt api-get https://example.com/api/review-requests/
+ {
+ ...
+ }
+
+As a convenience, you query arguments can be provided as command line options.
+A query string in the form of ``?<query-arg>=<value>`` can be provided as
+``--<query-arg>=<value>``. For example:
+
+.. code-block:: console
- $ # Make a request to http://example.com/api/review-requests/?counts-only=1
$ rbt api-get /review-requests/ --counts-only=1
+ {
+ ...
+ }
-.. rbt-command-usage::
.. rbt-command-options::
