.. restconf.py Example EXOS restconf client
   sphinx-quick start on Wed Dec 24 10:26:29 2014.
   You can adapt this file completely to your liking, but it should at least
   Contain the root `toctree` directive.

.. image:: ExtremeSwitchingLogo.png
.. image:: XosLogo.png

##################################
restconf ExtremeXOS Example Client
##################################
Version 1.1.0.4
===============
* Updated Installation Instructions

Disclaimer
==========
These Python scripts are provided free of charge by Extreme.  We hope such scripts are helpful when used in conjunction with Extreme products and technology; however, scripts are provided simply as an accommodation and are not supported nor maintained by Extreme.  ANY SCRIPTS PROVIDED BY EXTREME ARE HEREBY PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL EXTREME OR ITS THIRD PARTY LICENSORS BE LIABLE    FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE USE OR DISTRIBUTION OF SUCH SCRIPTS.

Minimum ExtremeXOS Required
===========================
EXOS 22.2
    The RESTCONF (RFC8040) interface began shipping with EXOS 22.4 release. To update the EXOS RESTCONF capabilities or add RESTCONF to previous versions of EXOS, the latest EXOS RESTCONF release may be obtained at:

        https://github.com/extremenetworks/EXOS_Apps/tree/master/REST/downloads

EXOS Command:

.. code-block:: bash

    download url https://github.com/extremenetworks/EXOS_Apps/raw/master/REST/downloads/summitX-restconf-2.0.2.12.xmod

Or

.. code-block:: bash

    download url https://github.com/extremenetworks/EXOS_Apps/raw/master/REST/downloads/summitX-restconf-2.0.2.12.xmod vr VR-Default

EXOS Display:

.. code-block:: bash

    Do you want to install image after downloading? (y - yes, n - no, <cr> - cancel) Yes

    Downloading to Switch...............
    Installing to primary partition!

    Installing to Switch...................
    Image installed successfully

Additional Documentation
========================
Once the EXOS download is complete, the RESTCONF reference document may be obtained directly from your EXOS switch at:

    http://<switch_address>/apps/restconfdoc

Example:
    For this example, the switch IP address is 10.68.65.81.

    On a web browser enter the following URL ``http://10.68.65.81/apps/restconfdoc``.

    *You will be prompted for proper switch credentials before being allowed to view the document.*


`Online EXOS RESTCONF API Reference Documentation <http://documentation.extremenetworks.com/exos/api/ProgramInterfaces/RESTCONF/RESTCONF.html>`_

Files
=====
The example RESTCONF script, available `here <https://github.com/extremenetworks/EXOS_Apps/tree/master/REST/examples>`_ provides an example server application which uses the EXOS RESTCONF interface.

The ``restconf.py`` class module contains the access methods for different EXOS RESTCONF methods. If you are developing your own Python RESTCONF client application, you may import this module and let it provide the basic handshake with EXOS.

.. csv-table:: RESTCONF Example Files
    :header: File, Description

    `restconf.py <https://github.com/extremenetworks/EXOS_Apps/raw/master/REST/examples/restconf.py>`_, EXOS restconf Python import to use with your applications
    `restget.py <https://github.com/extremenetworks/EXOS_Apps/raw/master/REST/examples/restget.py>`_, Example GET REST call
    `restdelete.py <https://github.com/extremenetworks/EXOS_Apps/raw/master/REST/examples/restdelete.py>`_, Example DELETE REST call

restconf.py Python module
-------------------------
The file ``restconf.py`` is a python class module that may be imported into your python applications. It encapsulates the RESTCONF communications with EXOS switches for you so you may focus on solving your business needs.

.. code-block:: python

    from restconf import Restconf


Restconf provides management methods for:

* Restconf.version()

    Returns the version string of this module
    
* Restconf.get(rest_url)

  - **rest_url** - 
    URL string sent to the EXOS switch during an HTTP GET operations.

        Example: ``/rest/restconf/data/openconfig-system:system``


* Restconf.post(rest_url, data)
* Restconf.put(rest_url, data)
* Restconf.patch(rest_url, data)

  - **rest_url** - 
    URL string sent to the EXOS switch during an HTTP POST/PUT/PATCH operations.

        Example: ``/rest/restconf/data/openconfig-vlan:vlans/vlan=<key>``, where <key> is the VLAN identifier

  - **data** - 
    Python dictionary for the HTTP message body. The dictionary is transformed into JSON before it is sent to the switch.


* Restconf.delete(rest_url)

  - **rest_url** - 
    URL string sent to the EXOS switch during an HTTP DELETE operation.

        Example: ``/rest/restconf/data/openconfig-vlan:vlans/vlan=<key>``, where <key> is the VLAN identifier of the VLAN to DELETE