Enable API on SMC
-----------------

In order to allow inbound API connections to the SMC, you must first enable the API service on the SMC management server.
To do this, open the SMC and edit the properties of the Management Server/s.

Under API Client, enable the API.
If SSL connections are required, import or self sign a certificate for use with the API service.

.. warning:: Do not check the "Use SSL for session ID" parameter when using this library. This setting is incompatible
	as the sessions are tracked using client sessions (for both HTTP and HTTPS)

Creating the session
--------------------

In order to interact with the SMC REST API, you must first obtain a valid login session. 
The session is generated by authenticating an API Client and the associated authentication key.

Once the login session has been retrieved successfully, all commands or controls will reuse 
the same session. 

When exiting, call `smc.api.web.logout()` to remove the active session from the Management Server.

.. note:: Idle API sessions will still time out after a default timeout on the Management Server.

Steps to enable API Communication on the Management Server:

#. Enable SMC API service on the properties of the Management Server
#. Create an API Client and obtain the 'authentication key'

Configuring credentials
+++++++++++++++++++++++

Credentials to obtain a session are obtained using the following methods (in order):

* Provide credentials in session.login() constructor

* In alternate specified file path (specified in login constructor)

* In INI configured file at users ~/.smcrc

* Environment variables

Each method is described in more detail below.

Method parameters
*****************

Example of providing the connect information through method parameters:

.. code-block:: python

   from smc import session

   session.login(url='http://1.1.1.1:8082', api_key='xxxxxxxxxxxxxxxxx')
   ....do stuff....
   session.logout()

If a specific API version is requested, you can add the following argument to the login
constructor. Otherwise the lowest API version available will be used.

To find supported versions using unauthenticated call to SMC API:
::

	>>> from smc.api.session import available_api_versions
	>>> available_api_versions('http://1.1.1.1:8082')
	[6.10, 7.1, 7.3]

Set up connection to specific version:

.. code-block:: python

   from smc import session
   session.login(url='http://1.1.1.1:8082', api_key='xxxxxxxxxxxxxxxxx', 
                 api_version='7.1')

Logging in to a specific Admin Domain:

.. code-block:: python

   session.login(url='http://1.1.1.1:8082', api_key='xxxxxxxxxxxxxxxxx', 
                 domain='mydomain')

.. note:: If an admin domain is specified but the SMC does not have domains configured, 
		  you will be placed in the 'Shared Domain'.
	
In order to use SSL connections, you must first associate a private key and certificate
with the SMC API server. This is done under the Management Server properties and SMC API.
Obtain the certificate for use by the client.
It is recommended to ensure your certificate has the subjectAltName field set per
RFC 2818.

Using SSL and specify certificate for verifying:

.. code-block:: python

   from smc import session
   session.login(url='https://1.1.1.1:8082', api_key='xxxxxxxxxxxxxxxx', 
                 verify='/Users/username/home/mycacert.pem')
   
Using SSL to the SMC API without SSL validation (NOT recommended)

.. code-block:: python

   from smc import session
   session.login(url='https://1.1.1.1:8082', api_key='xxxxxxxxxxxxxxxxxx',
                 verify=False)

.. seealso:: :meth:`smc.api.session.Session.login` for constructor arguments.

Configuration File
******************

It is possible to store the SMC connection information in ~/.smcrc in order to simplify
the login and eliminate the need to populate scripts with api key information. 
Syntax for ~/.smcrc:

.. code-block:: python

   [smc]
   smc_address=1.1.1.1
   smc_apikey=xxxxxxxxxxxxxxxxxxx
   api_version=7.1
   smc_port=8082
   smc_ssl=True
   verify_ssl=True
   ssl_cert_file='/Users/username/home/mycacert.pem'
   domain=mydomain
   
Then from launching scripts, you can do:

.. code-block:: python
	
	session.login()
	session.logout()

.. note:: It is possible to override the location of .smcrc by using the 'alt_filepath' argument in
          the login constructor.

.. code-block:: python

   session.login(alt_filepath='/home/somedir/test')

Environment Variables
*********************

If setting environment variables, the following are supported::

	SMC_ADDRESS=http://1.1.1.1:8082
	SMC_API_KEY=123abc
	SMC_CLIENT_CERT=path/to/cert
	SMC_TIMEOUT = 30 (seconds)
	SMC_API_VERSION = 7.1 (optional - uses lowest by default)
	SMC_DOMAIN = name of domain, Shared is default 

The minimum variables that need to be present are ``SMC_ADDRESS`` and ``SMC_API_KEY``::

	export SMC_ADDRESS = http://1.1.1.1:8082
	export SMC_API_KEY = foobarkey

Based on the session login constructor, you can also pass kwargs using the parameter `SMC_EXTRA_ARGS`.

Once the session has been successfully obtained, there is no reason to re-authenticate a new session
unless `logout` has been called.

.. note:: The SMC API will automatically purge idle sessions after a configurable amount of time.

Handling retries on server busy
+++++++++++++++++++++++++++++++

It is possible to override the default behavior for retrying a CRUD operation based on receiving a 
"Service Unavailable" (HTTP 503) response. By default, no retry is attempted.
You can override this behavior and allow the API to retry an operation using a backoff algorithm.

This can be enabled through the session login constructor using the `retry_on_busy` boolean or after
session login by calling `set_retry_on_busy`.
If called from session login, default parameters are provided for all retry related settings.
If you require more granularity, call after session login.

.. note:: By default, the following operation types are eligible for retry (GET/POST/PUT). You can
 override this by calling session.set_retry_on_busy(method_whitelist=['GET', 'POST', 'DELETE']) 

Calling from session login:

.. code-block:: python

	session.login(url='https://x.x.x.x:8082', api_key='xxxxxxxxxxxxxxx',
                  verify=False, timeout=30, retry_on_busy=True)

Calling after session login:

.. code-block:: python

	session.login()
	session.set_retry_on_busy(total=5, backoff_factor=0.1)
	...
	session.logout()

If you are using an preferences file, place the following into your .smcrc:

.. code-block:: python

  [smc]
  retry_on_busy=True
 
You can also set this on as an environment variable using the `SMC_EXTRA_ARGS` variable:

.. code-block:: python

	os.environ['SMC_EXTRA_ARGS'] = '{"retry_on_busy": "True"}'


Handling proxies
++++++++++++++++

To disable the use of an intermediate proxy and force the connection to go direct, you can add the following
environment variable:

.. code-block:: python

	os.environ['no_proxy'] = 'my.smc.at.domain'

Logging helper
++++++++++++++
		  
To enable logging from smc-python, you can utilize the standard python logger or use
convenience methods provided. These are typically called before session login:

.. code-block:: python

   from smc import set_file_logger
   set_file_logger(log_level=10, path='/Users/foo/smc-test.log')
   ...
   
Or use a stream logger and also optionally enable urllib3 messages:

.. code-block:: python

   from smc import set_stream_logger
   set_stream_logger(log_level=logging.DEBUG)
   set_stream_logger(log_level=logging.DEBUG, logger_name='urllib3')
   

Another logging option is to add the following lines to your script:

.. code-block:: python

   import logging
   logging.getLogger()
   logging.basicConfig(
       level=logging.DEBUG, format='%(asctime)s %(levelname)s %(name)s.%(funcName)s: %(message)s')

The ``format`` parameter follows the standard python logging module syntax.