.. _batchingrequests:

Batch Operations
================

The **Batch API** allows the client to send multiple AXAPI requests in a single call, which reduces round trips and improves performance.

Two endpoints are available:

* **Batch-Get** → for grouping multiple ``GET`` requests
* **Batch-Post** → for grouping multiple configuration (``POST``, ``PUT``, ``DELETE``) requests

.. contents::
   :local:
   :depth: 2

Batch-Get
---------

**Endpoint**

.. code-block:: html

   POST /axapi/v3/batch-get

**Description**

* Executes multiple ``GET`` requests in a single API call.
* Returns responses for all URIs in one aggregated response.
* Improves performance by reducing API call overhead.

**Intended Use and Limitations**

* Only the POST method is allowed.
* URIs ending with ``/schema`` (schema request calls) are not supported in Batch-Get operations. If attempted, they will fail. 

**Error Handling**

* If a URI is invalid, its corresponding ``resp`` will contain an error object.
* Other valid requests will still return results.

**Request Example**

.. code-block:: html

  POST /axapi/v3/batch-get
	{
	  "batch-get-list": [
		  {"uri": "/axapi/v3/interface/ethernet/1/schema"},
		  {"uri": "/axapi/v3/interface/ethernet?total=true"},
		  {"uri": "/axapi/v3/interface/ethernet?start=2&count=3"},
		  {"uri": "/axapi/v3/interface/ethernet?start=2&count=3&wrong-filter=xxx"},
		  {"uri": "/axapi/v3/interface/ethernet/1/oper"},
		  {"uri": "/axapi/v3/slb/server/s1/stats"},
		  {"uri": "/axapi/v3/no-such-endpoint"}
	  ]
	}

**Response Example**

.. code-block:: html

	{
	  "batch-get-list": [
		{
		  "uri":"/axapi/v3/interface/ethernet/1/schema",
		  "resp":{
			"http-status":400,
			"status":"fail",
			  "err": {
				"code":1023524864,
				"msg":"JSON message is wrong."
			  }
		  }
		},
		{
		  "uri":"/axapi/v3/interface/ethernet?total=true",
		  "resp":{
			"total-count":8
		  }
		},
		{
		  "uri":"/axapi/v3/interface/ethernet?start=2&count=3",
		  "resp":{
			"ethernet-list": [
			  {
				"ifnum":3,
				"l3-vlan-fwd-disable":0,
				"load-interval":300,
				"mtu":1500,
				"trap-source":0,
				"duplexity":"auto",
				"speed":"auto",
				"flow-control":0,
				"action":"disable",
				"uuid":"46e93848-844d-11e5-8d0b-000d480a65d0",
				"a10-url":"/axapi/v3/interface/ethernet/3"
			  },
			  {
				"ifnum":4,
				"l3-vlan-fwd-disable":0,
				"load-interval":300,
				"mtu":1500,
				"trap-source":0,
				"duplexity":"auto",
				"speed":"auto",
				"flow-control":0,
				"action":"disable",
				"uuid":"46e93c8a-844d-11e5-8d0b-000d480a65d0",
				"a10-url":"/axapi/v3/interface/ethernet/4"
			  },
			  {
				"ifnum":5,
				"l3-vlan-fwd-disable":0,
				"load-interval":300,
				"mtu":1500,
				"trap-source":0,
				"duplexity":"auto",
				"speed":"auto",
				"flow-control":0,
				"action":"disable",
				"uuid":"46e940c2-844d-11e5-8d0b-000d480a65d0",
				"a10-url":"/axapi/v3/interface/ethernet/5"
			  }
			]
		  }
		},
		{
		  "uri":"/axapi/v3/interface/ethernet?start=2&count=3&wrong-filter=xxx",
		  "resp":{
			"http-status":400,
			"status":"fail",
			  "err": {
				"code":1023524866,
				"msg":"Wrong URI filter."
			 }
		  }
		},
		{
		  "uri":"/axapi/v3/interface/ethernet/1/oper",
		  "resp":{
			"ethernet": {
			  "oper" : {
				"state":"DISABLED",
				"line_protocol":"DOWN",
				"link_type":"GigabitEthernet",
				"mac":"000d.480a.65cf",
				"config_speed":"auto",
				"actual_speed":"unknown",
				"config_duplexity":"auto",
				"actual_duplexity":"unknown",
				"media_type":"Copper"
			  },
			  "a10-url":"/axapi/v3/interface/ethernet/1/oper",
			  "ifnum":1
			}
		  }
		},
		{
		  "uri":"/axapi/v3/slb/server/s1/stats",
		  "resp":{
			"server": {
			  "stats" : {
				"curr-conn":0,
				"total-conn":0,
				"fwd-pkt":0,
				"rev-pkt":0,
				"peak-conn":0
			  },
			  "a10-url":"/axapi/v3/slb/server/s1/stats",
			  "name":"s1"
			}
		  }
		},
		{
		  "uri":"/axapi/v3/no-such-endpoint",
		  "resp":{
			"http-status":404,
			"status":"fail",
			  "err": {
				"code":1023525888,
				"msg":"URI not found."
			  }
		  }
		}
	  ]
	}

Batch-Post
----------

**Endpoint**

.. code-block:: html

  POST /axapi/v3/batch-post?config-version={version|none}&ignore-errors={true|false}

**Description**

* Executes multiple configuration requests (``POST``, ``PUT``, ``DELETE``) sequentially in a single API call.
* Each element must specify a ``uri``, ``method``, and a ``payload`` (for ``POST``/``PUT``). For ``DELETE``, the ``payload`` must be empty ({}).
* The ``config-version`` parameter ensures that requests are applied only if the device configuration version matches. 

**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 25 15 60

   * - Parameter
     - Required
     - Description
   * - ``uri``
     - Yes
     - AXAPI endpoint to call
   * - ``method``
     - Yes
     - One of ``post``, ``put``, ``delete`` (``get`` not supported)
   * - ``payload``
     - Yes
     - For ``post``/``put``, JSON request body for the operation
   * - ``ignore-errors``
     - No (query param)
     - ``false`` (default): stop on first failure, rollback previous requests.
       ``true``: continue execution, return errors inline.
   * - ``config-version``
     - No (query param)
     - Configuration version check before processing requests. 

**Behavior**

* With ``ignore-errors=false``:
  
  * Processing stops at the first failed element.
  * Response contains only the failure result.
  * All previous successful changes are rolled back.

* With ``ignore-errors=true``:
  
  * All requests are processed sequentially.
  * Failed elements return error objects in the result list.
  * Successful requests remain applied.

* With ``config-version``:
  
  * If the specified version matches the device’s current configuration version, the request is processed.
  * If the version does not match, the request fails with HTTP 400 and error message: ``Config version does not match current version``.
  * If set to ``none``, the request is processed without version validation.
  
**NOTE**: The ``config-version`` value is incremented automatically after each successful request. 

**Limitation**: Switching between partitions is not supported in Batch-Post. 

**POST Request Example (ignore-errors=true)**

.. code-block:: html

   POST /axapi/v3/batch-post?config-version=0.89&ignore-errors=true

   {
     "batch-post-list": [
       {
         "uri": "/axapi/v3/slb/server",
         "method": "post",
         "payload": {
           "server-list": [
             {
               "name": "s1",
               "host": "2.2.2.2",
               "action": "enable",
               "port-list": [
                 { "port-number": 80, "protocol": "tcp" }
               ]
             }
           ]
         }
       },
       {
         "uri": "/axapi/v3/interface/ethernet/1",
         "method": "post",
         "payload": {
           "ethernet": { "action": "enable" }
         }
       }
     ]
   }

**Response Example**

.. code-block:: json

   {
     "batch-post-list": [
       {
         "uri": "/axapi/v3/slb/server",
         "resp": {
           "server-list": [
             {
               "name": "s1",
               "host": "2.2.2.2",
               "use-aam-server": 0,
               "action": "enable",
               "template-server": "default",
               "conn-limit": 64000000,
               "no-logging": 0,
               "weight": 1,
               "slow-start": 0,
               "spoofing-cache": 0,
               "stats-data-action": "stats-data-enable",
               "extended-stats": 0,
               "uuid": "57e0ca7e-7170-11f0-927c-8a2e0803194f",
               "port-list": [
                 {
                   "port-number": 80,
                   "protocol": "tcp",
                   "range": 0,
                   "template-port": "default",
                   "action": "enable",
                   "no-ssl": 0,
                   "support-http2": 0,
                   "weight": 1,
                   "conn-limit": 64000000,
                   "no-logging": 0,
                   "stats-data-action": "stats-data-enable",
                   "extended-stats": 0,
                   "uuid": "57e1564c-7170-11f0-927c-8a2e0803194f",
                   "a10-url": "/axapi/v3/slb/server/s1/port/80+tcp"
                 }
               ],
               "a10-url": "/axapi/v3/slb/server/s1"
             }
           ]
         }
       }
     ]
   }

**DELETE Request Example**

.. code-block:: html

   POST /axapi/v3/batch-post?ignore-errors=false

.. code-block:: json

   {
     "batch-post-list": [
       {
         "uri": "/axapi/v3/cgnv6/lsn-lid",
         "method": "delete",
         "payload": {}
       },
       {
         "uri": "/axapi/v3/cgnv6/nat/pool-group",
         "method": "delete",
         "payload": {}
       },
       {
         "uri": "/axapi/v3/cgnv6/nat/pool",
         "method": "delete",
         "payload": {}
       }
     ]
   }

**Response**

.. code-block:: http

   HTTP/1.1 200 OK

.. code-block:: json

   {
     "batch-post-list": [
       {
         "uri": "/axapi/v3/cgnv6/lsn-lid",
         "resp": {
           "http-status": 200,
           "Status": "OK",
           "msg": "Success"
         }
       },
       {
         "uri": "/axapi/v3/cgnv6/nat/pool-group",
         "resp": {
           "http-status": 200,
           "Status": "OK",
           "msg": "Success"
         }
       },
       {
         "uri": "/axapi/v3/cgnv6/nat/pool",
         "resp": {
           "http-status": 200,
           "Status": "OK",
           "msg": "Success"
         }
       }
     ]
   }

Error Handling Example
-----------------------
The following example shows AXAPI requests that attempt to configure a non-existent service-group, using ignore-errors=true and ignore-errors=false to compare the outputs.

.. code-block:: json

   {
     "batch-post-list": [
       {
         "uri": "/axapi/v3/slb/server",
         "method": "post",
         "payload": {
           "server-list": [
             {
               "action": "enable",
               "host": "1.1.1.1",
               "name": "s1",
               "port-list": [
                 {
                   "port-number": 80,
                   "protocol": "tcp"
                 }
               ]
             }
           ]
         }
       },
       {
         "uri": "/axapi/v3/slb/service-group",
         "method": "post",
         "payload": {
           "service-group-list": [
             {
               "name": "s2",
               "protocol": "tcp",
               "member-list": [
                 {
                   "name": "s2",
                   "port": 80
                 }
               ]
             }
           ]
         }
       }
     ]
   }
   
**ignore-errors=false (default)**

Processing stops on first error.

.. code-block:: json

   {
     "response": {
       "http-status": 404,
       "status": "fail",
       "err": {
         "code": 1023460352,
         "msg": "Object specified does not exist"
       }
     }
   }

**ignore-errors=true**

All requests processed; failed ones return error.

.. code-block:: json

   {
     "batch-post-list": [
       {
         "uri": "/axapi/v3/slb/server",
         "resp": {
           "server-list": [
             {
               "name": "s1",
               "host": "1.1.1.1",
               "use-aam-server": 0,
               "action": "enable",
               "template-server": "default",
               "conn-limit": 64000000,
               "no-logging": 0,
               "weight": 1,
               "slow-start": 0,
               "spoofing-cache": 0,
               "stats-data-action": "stats-data-enable",
               "extended-stats": 0,
               "uuid": "5eac9326-7182-11f0-80d2-8a2e0803194f",
               "port-list": [
                 {
                   "port-number": 80,
                   "protocol": "tcp",
                   "range": 0,
                   "template-port": "default",
                   "action": "enable",
                   "no-ssl": 0,
                   "support-http2": 0,
                   "weight": 1,
                   "conn-limit": 64000000,
                   "no-logging": 0,
                   "stats-data-action": "stats-data-enable",
                   "extended-stats": 0,
                   "uuid": "5eb53080-7182-11f0-80d2-8a2e0803194f",
                   "a10-url": "/axapi/v3/slb/server/s1/port/80+tcp"
                 }
               ],
               "a10-url": "/axapi/v3/slb/server/s1"
             }
           ]
         }
       },
       {
         "uri": "/axapi/v3/slb/service-group",
         "resp": {
           "http-status": 204,
           "status": "OK",
           "msg": "No content."
         }
       }
     ]
   }