.. _start_here:

Start Here
===================

The aXAPI version 3.0 offers an HTTP interface that can be used to configure and monitor your ACOS device. The end-user can use the following HTTP methods to operate the AXAPI:

	1. POST
	2. GET
	3. PUT
	4. DELETE

Details about the usage of the above HTTP methods are covered in the :ref:`operations` section.

In general, the API user will perform the following sequence of steps:

	1. Log in: Request an authorization signature. See :ref:`logging-on` for details.
	2. Use HTTP methods (POST, GET, etc), along with the authorization signature retrieved in Step 1, to configure or monitor the ACOS device. See :ref:`api-call` for details.
	3. Log off: Inform the API that authorization is no longer needed for the signature retrieved in Step 1. See :ref:`logging-off` for details.

.. note:: aXAPIv3 operates over HTTPS


.. _logging-on:

Logging On
----------

This step is required to retrieve an authorization signature to be used to authenticate API calls. This is achieved by sending a POST request to the URI ``/axapi/v3/auth`` using using the credentials for the ACOS device, by inserting the following JSON payload::

	
	curl -k https://10.100.5.71/axapi/v3/auth \
	-H "Content-Type:application/json" \
	-d '{
	    "credentials": {
	        "username": "admin",
	        "password": "a10"
	    }
	}'

This example uses the default username ("admin") and default password ("a10") for the ACOS device.

If the credentials are valid, the API will return a JSON response like the one below::

	{
	  "authresponse" : {
	  "signature":"ea697a2bc0eb6ec9a1ec7723a3c9b0",
	  "description":"the signature should be set in Authorization header for following request."
	   }
	}

The value of the signature attribute (ea697a2bc0eb6ec9a1ec7723a3c9b0, in this example) should be used for future aXAPI operations within an HTTP Authorization header, which will be discussed later.


.. _api-call:

Making an API call
------------------

As mentioned earlier, the end-user interacts with the aXAPI using the HTTP methods listed in the :ref:`operations` section. The end-user is required to use an HTTP Header named ``Authorization`` with a value equal to ``A10 <signature>``, where signature is the authorization signature obtained during the :ref:`logging-on` stage.

Each object is identified by a URI.

For instance, in order to create an SLB virtual server, we would make the following POST request on the object's URI ``/axapi/v3/slb/virtual-server``::

	curl -k POST https://10.100.5.71/axapi/v3/slb/virtual-server \
	-H "Content-Type:application/json" \
	-H "Authorization: A10 ea697a2bc0eb6ec9a1ec7723a3c9b0" \
	-d '{
		"virtual-server": {
			"name": "a",
			"ip-address": "4.4.4.4",
			"enable-disable-action": "enable",
			"redistribution-flagged": 0,
			"arp-disable": 0,
			"policy": 0,
			"virtual-server": 0,
			"logging": 0,
			"stats-data-action": "stats-data-enable",
			"extended-stats": 0,
			"port-list": [
				{
					"port-number": 0,
					"protocol": "tcp",
					"range": 0,
					"conn-limit": 8000000,
					"reset": 0,
					"no-logging": 0,
					"use-alternate-port": 0,
					"action": "enable",
					"def-selection-if-pref-failed": "def-selection-if-pref-failed",
					"ha-conn-mirror": 0,
					"skip-rev-hash": 0,
					"message-switching": 0,
					"force-routing-mode": 0,
					"reset-on-server-selection-fail": 0,
					"clientip-sticky-nat": 0,
					"extended-stats": 0,
					"snat-on-vip": 0,
					"stats-data-action": "stats-data-enable",
					"syn-cookie": 0,
					"no-auto-up-on-aflex": 0,
					"no-dest-nat": 0,
					"enable-scaleout": 0,
					"auto": 0,
					"ipinip": 0,
					"use-rcv-hop-for-resp": 0,
					"template-tcp": "default",
					"template-virtual-port": "default",
					"use-default-if-no-server": 0,
					"a10-url": "https://100.31.1.101/axapi/v3/slb/virtual-server/a/port/0+tcp"
				}
			]
		}
	}'


.. _logging-off:

Logging Off
-----------

This step is required to indicate to the ACOS device that all aXAPI operations have been completed for the current authorized session. This is achieved by sending a POST request to the URI ``/axapi/v3/logoff`` along with the authorization header and content-type header discussed in the :ref:`api-call` section.


Contents
--------

.. toctree::
	:maxdepth: 2
	
	self
	how_to_use.rst
	resources.rst
	operations.rst
	workflow.rst
	filters.rst