Feature/SK-1235 | Improve API documentation

docs/apiclient.rst

@@ -1,13 +1,12 @@
 .. _apiclient-label:
 
-Using the FEDn API Client
+Using the API Client
 ====================
 
-FEDn comes with an *APIClient* - a Python3 library that can be used to interact with FEDn programmatically. 
-In this tutorial we show how to use the APIClient to initialize the server-side with the compute package and seed models, 
-run and control training sessions, use different aggregators, and to retrieve models and metrics. 
+FEDn comes with an *APIClient* - a Python3 library that is used to interact with FEDn programmatically. 
 
-We assume a basic understanding of the FEDn framework, i.e. that the user has taken the :ref:`quickstart-label` tutorial.
+This guide assumes that the user has aleady taken the :ref:`quickstart-label` tutorial. If this is not the case, please start there to learn how to set up a FEDn Studio project and learn 
+to connect clients. In this guide we will build on that same PyTorch example (MNIST), showing how to use the APIClient to control training sessions, use different aggregators, and to retrieve models and metrics. 
 
 **Installation**
 
@@ -17,14 +16,22 @@ The APIClient is available as a Python package on PyPI, and can be installed usi
 
    $ pip install fedn
 
-**Initialize the APIClient to a FEDn Studio project**
+**Connect the APIClient to the FEDn project**
 
-The FEDn REST API is available at <controller-host>/api/v1/. To access this API you need the url to the controller-host, as well as an admin API token. The controller host can be found in the project dashboard (top right corner).
-To obtain an admin API token, 
+To access the API you need the URL to the controller-host, as well as an admin API token. You 
+obtain these from your Studio project. The controller host can be found in the top-right corner of the dashboard:
+
+.. image:: img/find_controller_url.png
+
+To obtain an admin API token,  
 
 #. Navigate to the "Settings" tab in your Studio project and click on the "Generate token" button. 
 #. Copy the 'access' token and use it to access the API using the instructions below. 
 
+.. image:: img/generate_admin_token.png
+
+To initalize the connection to the FEDn REST API: 
+
 .. code-block:: python
 
    >>> from fedn import APIClient
@@ -43,6 +50,11 @@ Then passing a token as an argument is not required.
    >>> from fedn import APIClient
    >>> client = APIClient(host="<controller-host>", secure=True, verify=True)
 
+We are now ready to work with the API. 
+
+We here assume that you have worked through steps 1-2 in the quisktart tutorial, i.e. that you have created the compute package and seed model on your local machine. 
+In the next step, we will use the API to upload these objects to the Studio project (corresponding to step 3 in the quickstart tutorial).  
+
 **Set the active compute package and seed model**
 
 To set the active compute package in the FEDn Studio Project:
@@ -69,6 +81,8 @@ using the default aggregator (FedAvg):
    >>> model_id = models[-1]['model']
    >>> validations = client.get_validations(model_id=model_id)
 
+You can follow the progress of the training in the Studio UI. 
+
 To run a session using the FedAdam aggregator using custom hyperparamters: 
 
 .. code-block:: python
@@ -130,9 +144,10 @@ To get a specific session:
 
    >>> session = client.get_session(id="session_name")
 
-For more information on how to use the APIClient, see the :py:mod:`fedn.network.api.client`, and the collection of example Jupyter Notebooks:
+For more information on how to use the APIClient, see the :py:mod:`fedn.network.api.client`.  
+There is also a collection of Jupyter Notebooks showcasing more advanced use of the API, including how to work with other built-in aggregators and how to automate hyperparameter tuning:
 
-- `API Example <https://github.com/scaleoutsystems/fedn/tree/master/examples/notebooks>`_  . 
+- `API Example <https://github.com/scaleoutsystems/fedn/tree/master/examples/api-tutorials>`_  . 
 
 
 .. meta::