HomeGuidesAPI Reference
v8.0
GuidesAPI ReferenceGitHubAirheads Developer CommunityLog In
Guides
GuidesAPI ReferenceGitHubAirheads Developer Community

POST

In this section we will see how to make a POST request to the Mobility Conductor. POST method is used to add new data and modify or delete existing data in the system. We currently do not support HTTP PUT and HTTP DELETE. However, the same is achieved using HTTP POST.

  • Once the authentication token (UIDARUBA) is obtained using login endpoint, you can start interacting with the system to add/modify/delete data using the various API endpoints available

📘

Note

You can send as many objects as you want in a request as long as the complete request does not exceed 1 MB

POST Request

Syntax for POST request using cURL: 

curl -b "aruba-cookie" -X POST --header "Content-Type: application/json" --header "Accept:application/json" -d @payload.json -k 'https://<mcr-ip>:4343/v1/configuration/object?config_path=<config-node>&UIDARUBA=<session-token>' -v

📘

Note:

--insecure or -k option is used with the cURL command if the certificate of the Mobility Conductor cannot be validated
-b is used to read the cookie from "aruba-cookie" file
-d is used to send the data consisting of a json file for json payload
-v is used for Verbose Mode

Description of user-specific values used in the cURL example

1183

cURL values - POST

POST API Request

Request URL:
https://< mcr-ip >:4343/v1/configuration/object

Request Query Parameters:
config_path:
UIDARUBA:

Request Headers:
Content-Type: application/json
Accept: application/json
Cookie: SESSION=

Request Payload/Data:

  • Data contains an endpoint or multiple endpoints which need to be configured
  • Each object/endpoint can contain either an array of instances, a single instance of multiple objects,
    or a single object
  • Every object or sub-object can contain another field called "_action" which describes the action applied to the configuration object. If this parameter is not present it implies that the user wants to add/modify the configuration. This field is mandatory if trying to delete any configuration.

"_action" can take the following values:
"add" – (DEFAULT) Add this new object and if already present, it will replace the old object with new object. If "_action" in not present, by default it will try to add the configuration

"modify" – Modify an existing object to change either an instance or sub-instance of an object

"delete" – Delete the instance of a multi-instance object or delete the full object for a single instance object

"noop" – No action is required for this object. It is used in cases where some objects in a container are not modified or deleted

Let us see a brief example about how these different things can be implemented using a POST request. Consider using some of the VLANs as interface VLANs.
In the example below you will find the JSON payload for achieving the following:

  • Creating two Interface VLANs namely, Interface VLAN 198 and 199
  • Modifying Interface VLAN 199
  • Deleting Interface VLAN 199

Sample Configuration or Payload File to add new configuration
Endpoint/Object: int_vlan (Interface VLAN)

{
   "int_vlan":[
      {
         "id":198,
         "int_vlan_ip":{
            "ipaddr":"100.1.1.1",
            "ipmask":"255.0.0.0"
         }
      },
      {
         "id":199,
         "_action":"add",
         "int_vlan_ip":{
            "ipaddr":"111.1.1.1",
            "ipmask":"255.0.0.0",
            "_action":"add"
         },
         "int_vlan_mtu":{
            "value":"1300",
            "_action":"add"
         }
      }
   ]
}

The above payload is for creating new Interface VLANs, VLAN 198 and VLAN 199 with the configuration parameters given as sub-objects for each VLAN.
Sub-objects: For VLAN 198, we have added the VLAN Interface IP address and for VLAN 199 we have added the VLAN Interface IP address as well as the Interface VLAN MTU value.

📘

Note

If sub-objects are not mentioned, then the object will configure the default values for that object if any.
Example: If a VLAN Interface (int_vlan) is created like VLAN 198 with only the interface IP address, then it will take the default values for all other sub-objects, if present.

Sample Configuration or Payload File to modify existing configuration 

# Option 1
{
   "int_vlan":[
      {
         "id":199,
         "_action":"modify",
         "int_vlan_ip":{
            "ipaddr":"111.1.1.1",
            "ipmask":"255.0.0.0",
           "_action": "noop"
         },
         "int_vlan_mtu":{
            "value":"1450",
            "_action":"modify"
         }
      }
   ]
}


#OR payload can be given as follows:
# Option 2

{
   "int_vlan":[
      {
         "id":199,
         "_action":"modify",
         "int_vlan_mtu":{
            "value":"1500",
            "_action":"modify"
         }
      }
   ]
}

Sample Configuration or Payload File to delete existing configuration
Steps for deleting an Interface VLAN:

  • Delete the IP address assignment
  • Delete the Interface VLAN
{
   "int_vlan":[
      {
         "id":199,
         "int_vlan_ip":{
            "ipaddr":"111.1.1.1",
            "ipmask":"255.0.0.0",
           "_action": "delete"
         }
      },
     {
         "id":199,
         "_action": "delete"
      }
		
   ]
}

The same JSON payload from a POST request is returned in a POST response with the addition of “_result” and “_global_result” fields, as shown below:

 

POST Response

Sample JSON Response for a successful POST request

{
   "int_vlan":
      {
         "id":198,
         "_action":"add",
         "int_vlan_ip":{
            "ipaddr":"111.1.1.1",
            "ipmask":"255.0.0.0",
            "_action":"add",
            "_result":{
               "status":0,
               "status_str":""
            }
         },
         "int_vlan_mtu":{
            "value":"1400",
            "_action":"add",
            "_result":{
               "status":0,
               "status_str":""
            }
         },
         "_result":{
            "status":0,
            "status_str":""
         }
      }
}

The POST response payload is identical to the POST request payload, except for additional “_result” fields for each object, sub-object, and “_global_result” fields. This is composed of two sub-objects: "status" and "status_str":

  1. "status": If the "status" is 0, it implies successful execution of the specified action. The results of "status" is displayed in "status_str".
  2. "status_str": This only displays notices or outputs. In case the "status" is non-zero, it carries an error message in the "status_str" for the executioner of the API.
  • Similarly to get the status of the complete query, there is a field called "_global_result" which returns the first error that was received from the system or "Success" if there were no errors.
  • There is another field, which is present in global result but not present in per object results: “_pending”, the value of which can be 1 or 0.
    • 1 means that the config node for which POST request was sent, is now in pending state, waiting for the changes to be deployed.
    • 0 means that it is not in pending state (in committed state).

The POST request is best effort and in case of first failure, others in the same block are not even tried. The error in such a case will be as follows:
"Error detected in previous object. Bypassing this object".

Write Memory API

On getting a successful response from a POST request, it is certain that some changes are waiting to be deployed on the system. After reviewing whether the correct configuration is pushed using previous POST requests for a given configuration path in the node hierarchy, you can deploy the configuration changes by using the write_memory API endpoint.

As a best practice, you should combine all the changes to be made at a configuration node in the hierarchy. Once the changes are made using various API and reviewed, the pending changes should be applied on that node using the write_memory API before moving over to another node in the hierarchy.

The following is an example of Write Memory API in cURL to save pending changes

📘

Note

The write_memory endpoint should be called via it's own API request and no other POST requests for any other payload should be present along with write_memory. This is because processing of this object can take time.

curl –b "aruba-cookie" –X POST –i 'https://<mcr-ip>:4343/v1/configuration/object/write_memory?config_path=<config-node>&UIDARUBA=<session-id>' –d "{}"

Request URL:
https://:4343/v1/configuration/object/write_memory

Request Query Parameters:
config_path: <config_node>
UIDARUBA:

Request Headers:
Content-Type: application/json
Accept: application/json
Cookie: SESSION=

Request Payload
Null Data or Empty Dictionary

📘

Note

You can use the --insecure or -k option with the cURL command if the certificate of the Mobility Conductor cannot be validated.

Response for successful Write Memory operation

{
"write_memory": {
"_result": {
"status": 0,
"status_str": "Command executed."
} },
"_global_result": { "status": 0, "status_str": "Success"
} }

👍

Available Endpoints

To view the list of all the available endpoints click here.

📘

Note:

DELETE method is not supported, however POST method is used to delete or modify data in the system

 

Updated almost 2 years ago