Basic Concepts
==============

Familiarizing yourself with the following underlying basic concepts will help you get up
and running with the SDK.

.. include:: SDK_plural_note.rst

REST URIs
---------

You can directly infer REST URIs from the python expressions, and vice versa.

.. topic:: Examples

    .. code-block:: python

        Expression:     mgmt = ManagementRoot('<ip_address>', '<username>', '<password>')
        URI Returned:   https://<ip_address>/mgmt/

    .. code-block:: python

        Expression:     cm = mgmt.cm('<ip_address>', '<username>', '<password>')
        URI Returned:   https://<ip_address>/mgmt/cm

    .. code-block:: python

        Expression:     tm = mgmt.tm('<ip_address>', '<username>', '<password>')
        URI Returned:   https://<ip_address>/mgmt/tm


    .. code-block:: python

        Expression:     ltm = mgmt.tm.ltm('<ip_address>', '<username>', '<password>')
        URI Returned:   https://<ip_address>/mgmt/tm/ltm/


    .. code-block:: python

        Expression:     pools1 = mgmt.tm.ltm.pools
        URI Returned:   https://<ip_address>/mgmt/tm/ltm/pool


    .. code-block:: python

        Expression:     pool_a = pools1.create(partition="Common", name="foo")
        URI Returned:   https://<ip_address>/mgmt/tm/ltm/pool/~Common~foo


REST Endpoints
--------------
A set of basic REST endpoints can be derived from the object's URI and ``kind`` (listed below).

  - |Organizing Collection Section|
  - |Collection Section|
  - |Resource Section|
  - |Unnamed Resource Section|
  - |Subcollection Section|
  - |Subcollection Resource Section|


Dynamic Attributes
------------------

The python object's attribute can be created dynamically based on the JSON returned when
querying the REST API.

.. _kind_params_section:

iControl® REST ``kind`` Parameters
----------------------------------

Almost all iControl® REST API entries contain a parameter named ``kind``. This parameter
provides information about the object that lets you know what you should expect to follow
it. The iControl® REST API uses three types of ``kind``: ``collectionstate``, ``state``,
and ``stats``.

.. table::

   +---------------------+---------------------------+------------------------------------------+
   | Kind                | Associated Objects        | Methods                                  |
   +=====================+===========================+==========================================+
   | ``collectionstate`` | * |Organizing Collection| | |exists|                                 |
   |                     | * |Collection|            |                                          |
   +---------------------+---------------------------+------------------------------------------+
   | ``state``           | |Resource|                | * |create|                               |
   |                     |                           | * |update|                               |
   |                     |                           | * |refresh|                              |
   |                     |                           | * |delete|                               |
   |                     |                           | * |load|                                 |
   |                     |                           | * |exists|                               |
   +---------------------+---------------------------+------------------------------------------+
   | ``state``           | |Unnamed Resource|        | * |update|                               |
   |                     |                           | * |refresh|                              |
   |                     |                           | * |load|                                 |
   |                     |                           | * |exists|                               |
   +---------------------+---------------------------+------------------------------------------+
   | ``stats``           | |Resource|                | * |refresh|                              |
   |                     |                           | * |load|                                 |
   |                     |                           | * |exists|                               |
   +---------------------+---------------------------+------------------------------------------+


.. _methods_section:

Methods
-------

.. table::

   +-----------+---------------+-------------------------------------------------------------------+
   | Method    | HTTP Command  | Action(s)                                                         |
   +===========+===============+===================================================================+
   | |create|  | POST          | | creates a new resource on the device with its own URI           |
   +-----------+---------------+-------------------------------------------------------------------+
   | |exec_cmd|| POST          | | executes commands on applicable unnamed resources               |
   +-----------+---------------+-------------------------------------------------------------------+
   | |update|  | PUT           | | submits a new configuration to the device resource; sets the    |
   |           |               | | Resource attributes to the state reported by the device         |
   +-----------+---------------+-------------------------------------------------------------------+
   | |modify|  | PATCH         | | submits a new configuration to the device resource; sets only   |
   |           |               | | the attributes specified in `modify` method. This is different  |
   |           |               | | from `update` because update will change all the attributes, not|
   |           |               | | only the ones that you specify.                                 |
   +-----------+---------------+-------------------------------------------------------------------+
   | |refresh| | GET           | | obtains the state of a device resource; sets the representing   |
   |           |               | | Python Resource Object; tracks device state via its attributes  |
   +-----------+---------------+-------------------------------------------------------------------+
   | |delete|  | DELETE        | | removes the resource from the device, sets ``self.__dict__``    |
   |           |               | | to ``{'deleted': True}``                                        |
   +-----------+---------------+-------------------------------------------------------------------+
   | |load|    | GET           | | obtains the state of an existing resource on the device; sets   |
   |           |               | | the Resource attributes to match that state                     |
   +-----------+---------------+-------------------------------------------------------------------+
   | |exists|  | GET           | | checks for the existence of an object on the BIG-IP®            |
   +-----------+---------------+-------------------------------------------------------------------+

.. note::

    Available methods are restricted according to the object's ``kind``.




