.. _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.10.10.10/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 a DDOS Zone (z15) with an IP subnet address, TCP, and UDP ports, make the following POST request on the object’s URI /axapi/v3/ddos/dst/zone with the following JSON body (the following example uses a separate text file with the JSON body content)::

	curl -X POST https://10.10.10.10/axapi/v3/ddos/dst/zone/ 
	-H "Authorization: A10 ea697a2bc0eb6ec9a1ec7723a3c9b0" 
	-k -H "Content-type: application/json" --data @filename
	{
	  "zone-list": [
		{
		  "zone-name":"z15",
		  "ip": [
			{
			  "subnet-ip-addr":"10.10.15.0/24"
			}
		  ],
		  "port": {
			"zone-service-list": [
			  {
				"port-num":53,
				"protocol":"udp"      
			  },
			  {
				"port-num":80,
				"protocol":"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