.. _rest_tutorial:
RESTCONF 
====================================

NETCONFc supports connecting to a RESTCONF server
and perform RESTCONF actions.

.. _new_connection:

Connect to server via RESTCONF over HTTP 
------------------------------------------
    Start NETCONFc, you will see NETCONFc' main YANG ``Module Explorer`` 
    window.
   
    .. image:: images/connect_toolbar_restconf.*     
     
    Click the ``Connect`` button, select ``RESTCONF`` to bring up the session creation dialog.   

    .. image:: images/session_creation_restconf.*   

.. _new_connection_parameter:
    
    
    |
    |
    **New session parameters**
    
    Enter server's host name or IP address, port number.
    Enter your user name and password if HTTP Auth is used. ``HTTP Auth`` can be either ``Basic Auth`` or ``Digest Auth`` depending on the server configuration.
    
    If ``HTTPS`` scheme is selected, then you must enter the ``trusted CA certificate`` file with full path,
    which is needed to validate the server's certificate and can be a chained certificate file.    
    You can disable ``Verify Server Cert`` to prevent NETCONFc client from enforcing verifying server's certficate.

    If the server requires a valid client certificate, then you must
    enter ``client certificate`` file with full path, 
    ``client private key`` file with full path (this field can be left blank if the client certificate 
    file already contains client's private key).
    
    ``YANG Encode`` can be either ``JSON-encoding`` or ``XML-encoding`` depending on what the server supports.
    
    .. note::        
        ``timeout`` is the time NETCONFc will abort connecting if no response has been received after that period of time
    
    
    Then click the button "Connect" on the session creation 
    dialog. You should be connected to the server. 

    If error occurs, check if the server is running on the specified 
    address and port. Also make sure the correct user name and password 
    are used.

        

.. _basic_get:
        
Send <Get> requests
----------------------------------------------------

    You can select one or more nodes in the module tree and send a <get> to retrieve current data (state and config) underneath.
    
    Use the key shortcut ``Ctrl + Z`` to quickly perform <get> request.    
    
    If you ``Ctrl + Z`` on the ``module`` node, then all state and config data in that module will be retrieved.
    
    In the notebook in the window on the right side , you will also see a RPC XML page that 
    shows the XML encoding of the last RPC request and reply.
    
    There is also a notebook page that is either labeled as ``datatree``
    or ``<Get-config data tree (Value is editable)>``. It shows a tree view for the retrieved instance 
    data. We call it ``data tree``.

    If the get is not issued for config data, then the ``data tree`` is read-only. In other words, the cells in the ``Value`` column
    will not allow editing. The edit-config in the right-click context menu is also disabled.
        
    You can use <Shift + click> or <Ctrl + click> to select multiple nodes for retrieving data
    
    .. image:: images/find_session_id.*
    
    .. note::     
        When you <get> on a leaf node in a list, if the server does not send back the value for 
        the list key nodes at the same time, then you will not make much sense out of the 
        data you received. NETCONFc by default will include all key nodes when querying data. 
        To turn this feature off see :ref:`retrieval_with_key`
    
.. _basic_get_config:
         
Send <Get> requests for config data
-----------------------------------------
    
    You can send a <get> to retrieve the config data underneath a node.
    
    Select any node, right click and select 'Set Retrieval Options | Content | config' to retrieve the config data under this node.
    
    Then use the key shortcut ``Ctrl + Z`` to perform <get> request.   

    In this case, the data retrieved and shown on the right window pane is read-write. In other words, the cells in the 
    ``Value`` allows editing. The edit-config in the right-click context menu is also enabled.
    
.. _basic_head:
         
Send <Head> and <Options> requests for config data
-----------------------------------------
      You can select one or more nodes in the module tree and send a <Head>  or <Options> requests on them.
    

Set Retrieval Options
-----------------------------------------
        
    Select any node, right click and select 'Set Retrieval Options'.
    
    You can insert headers such as ``If-Match``, ``If-None-Match``, ``If-Modified-Since``, and ``If-Unmodified-Since`` 
    headers in your requests by selecting the menu ``Insert Selected Headers in Requests``
    
    You can insert ``depth`` parammeter by entering a non-zero value in the ``Depth`` field on the top toolbar.
    
    You can insert ``with-defaults`` parameter such  as ``trim``, ``explicit``, ``report-all`` and ``report-all-tagged`` 
    by selecting the menu ``With-defaults``.
    
    When sending a get request, its ``fields`` filter expression will be built automatically if you use 'Ctrl + Click' 
    to select two or more nodes, " + value, caption="Set up fields filter expression")
    
        
.. _basic_edit_yang_tree:    
 
Send <Post> <Put> <Patch> command
--------------------------------------------------------

    We call the YANG module tree on the left side ``schema tree``
    
    To create or edit a node in the remote server config, just select the node in the module tree,  
    right-click and select ``Enter Value to include in RPC`` or use shortcut key ``Ctrl + W``.
        
	.. image:: images/enter_value_dropdown.*
        
    You can also click the ``Value`` cell to enter or modify the value you want to set.
    
    You can choose a target node by right-clicking and select ``Set/Unset selected  node as edit target``. 
    If no target node is chosen the application will try to pick one for you based on the values you entered. 
    However the target node automatically chosen may not be what you intend to use.
    
    After you finish entering the value,  right-click and select ``Post``, ``Put``, or ``Patch`` to send it.

       
.. _basic_edit_instance_tree:    

    
More Operations
---------------------------------
    You can send the following operations through this pull-down menu.

    ``Get YANG Library version``
    
    ``Send a get on Datastore Resource``
    
    ``Get All Operations Resource``
    
    
Sending Raw RESTCONF Requests
---------------------------------
    You can send manually edited RESTCONF requests directly in the ``Send Request and Show Reply`` tab window.
    
    Using this feature you can modify a RESTCONF message and resend it quickly.
    
    For example, you can send a <get> request. Then in the "Send Request and Show Reply"
    window, you should see the last request and reply message. 
    
    You may want to change some fields  (e.g. the `depth parameter value`) and then simply click 
    ``Send Request above (Type URL Data)`` to resend the get request.
    
    This can be a handy way to test your server and see how it responds to various requests. 

    