Consolidate Your WAPIs Using the Request Object

[#1]

by Krishna Vasudevan, Infoblox Technical Marketing Engineer

Infoblox offers Web-based Application Programming Interfaces, also called WAPIs, that are REST-based and allows you to easily integrate NIOS into your automation environment.

This article talks about why you need to use WAPIs. Some workflows using WAPIs require multiple API calls. Below are a few examples of such workflows and the steps involved:

• Deleting a host record:
  1. Get the object reference of the host record in question
     
     curl -k -u admin:infoblox -X GET "https://127.0.0.1/wapi/v2.10/record:host?name=host1.info.com&_return_as_object=1"
     
     
  2. Issue a call to delete it
     
     curl -k -u admin:infoblox -H 'content-type: application/json' -X DELETE "https://127.0.0.1/wapi/v2.10/record:host/ZG5zLmhvc3QkLl9kZWZhdWx0LmNvbS5pbmZvLmhvc3Qx:host1.info.com..."
     
     
• Enable DHCP Service on a member:
  1. Get the object reference of the member DHCP properties object
     
     curl -k -u admin:infoblox -X GET "https://127.0.0.1/wapi/v2.10/ member:dhcpproperties?_return_as_object=1"
     
     
  2. Issue a call to enable the DHCP service
     
     curl -k -u admin:infoblox -H 'content-type: application/json'-X PUT "https://127.0.0.1/wapi/v2.10/member:dhcpproperties/ZG5zLm1lbWJlcl9kaGNwX3Byb3BlcnRpZXMkMQ:member1.lo..." -d '{"enable_dhcp":true}'
     
     

To simplify these workflows and use a single WAPI call to issue multiple commands, you can use the /request object.

The request object

This object allows the control of WAPI through a single-entry point. The object supports only the POST method and does not support URI arguments.

The request object supports both single object requests and multiple object requests.

Single object body requests can be used for any supported WAPI operations, including scheduling and approval. Only HTTP methods (GET, PUT, DELETE and POST) are valid methods for the single object body requests.

Multiple object body requests are composed of a list of single requests. Using this, you can combine multiple WAPI calls.

Fields supported

The following fields are supported as part of the multiple object body request:

Field	Type	Description	Supported values
data	Dictionary	Data that is dependent on the method and is sent in the body of a normal WAPI request.
args	Dictionary	Arguments for object body requests. These arguments are appended to the URI in a normal WAPI request.	_function, _schema, _return_fields, _return_fields+, _return_as_object, _max_results
method	String	Method of the operation. Supported methods include the HTTP methods and STATE object methods.	GET, PUT, POST, DELETE, STATE:ASSIGN, STATE: DISPLAY
object	String	The object used for the operation.	For a normal WAPI, this can either be an object type such as ‘network’ for a GET operation, or a WAPI object such as ‘network/dAs4...’ for a PUT operation.
enable_substitution	Boolean	Determines if the variables created in the stated request can be used for the current operation.	true, false
assign_state	Dictionary	Fields of the result object in the current operation, which should be saved in the request state object for the next operation in the multiple object body request. This also supports saving the extensible attribute value and a specific array member.
discard	Boolean	If set to true, result of the current operation will be skipped and will not be added to the returned result list.	true, false

 

STATE methods

In addition to the standard HTTP methods, the multiple object body request supports the following values:

Method	Description
STATE:ASSIGN	Copy fields in the data object to the state object.
STATEISPLAY	Add the state object to the returned result list.

 

Multiple Object Body Request Examples

• Deleting a host record:
  
  curl -k -u admin:infoblox -H 'content-type:application/json' -X POST "https://127.0.0.1/wapi/v2.10/request" -d '[{"method": "STATE:ASSIGN","data":{"host_name":"host1.info.com"}},{"method":"GET","object": "record:host","data": {"name":"##STATE:host_name:## "},"assign_state": {"host_ref": "_ref"},"enable_substitution": true,"discard": true},{ "method": "DELETE", "object": "##STATE:host_ref:##","enable_substitution": true,"discard": true},{"method": "STATEISPLAY"}]'
  
  

Let us look at each step separately:

1. {"method": "STATE:ASSIGN",
   "data":{"host_name":"host1.info.com"}}
   This step assigns the value “host1.info.com” to the variable “host_name” in the state object.
2. {"method":"GET",
   "object": "record:host",
   "data": {"name":"##STATE:host_name:## "},
   "assign_state": {"host_ref": "_ref"},
   "enable_substitution": true,
   "discard": true}
   This step issues a GET request to fetch the host record with the name stored in the “host_name” variable from the previous step (host1.info.com), and stores the “_ref” in the output to the variable “host_ref” in the state object. The result of this operation will not be displayed in the final output list.
3. { "method": "DELETE",
   "object": "##STATE:host_ref:##",
   "enable_substitution": true,
   "discard": true}
   This step issues a DELETE request to delete the host record using the object reference stored in “host_ref” variable from the previous step. The result of this operation will not be displayed in the final output list.
4. {"method": "STATEISPLAY"}
   This step displays the all the variables stored in the state object along with the result list.

Final output looks like below:

[{"host_name": "host1.test.com",

  "host_ref": "record:host/ZG5zLmhvc3QkLl9kZWZhdWx0LmNvbS50ZXN0Lmhvc3Qx:host1.test.com/default"}]

• Enable DHCP Service on a member:

curl -k -u admin:infoblox -H 'content-type:application/json' -X POST "https://127.0.0.1/wapi/v2.10/request" - d '[{"method": "STATE:ASSIGN","data":{"member_name":"member1.localdomain"}},{"method":"GET","object": "member:dhcpproperties","data": {"host_name":"##STATE:member_name:##"},"assign_state": {"host_ref": "_ref"},"enable_substitution": true,"discard": true},{ "method": "PUT", "object": "##STATE:host_ref:##","enable_substitution": true,"data": {"enable_dhcp":true}},{"method": "STATEISPLAY"}]'

Let us look at each step separately:

1. {"method": "STATE:ASSIGN",
   "data":{"member_name":"localdomain"}}
   This step assigns the value “member1.localdomain” to the variable “member_name” in the state object.
2. {"method":"GET","object":
   "member:dhcpproperties",
   "data": {"host_name":"##STATE:member_name:##"},
   "assign_state": {"host_ref": "_ref"},
   "enable_substitution": true,
   "discard": true}
   This step issues a GET request to fetch the DHCP properties of the member with the name stored in the “member_name” variable from the previous step (member1.localdomain), and stores the “_ref” in the output to the variable “host_ref” in the state object. The result of this operation will not be displayed in the final output list.
3. { "method": "PUT",
   "object": "##STATE:host_ref:##",
   "enable_substitution": true,
   "data": {"enable_dhcp":true}}
   This step issues a PUT request to modify the member DHCP properties using the object reference stored in “host_ref” variable from the previous step. The output from this step is displayed.
4. {"method": "STATEISPLAY"}
   This step displays the all the variables stored in the state object along with the result list.

Final output looks like below:

["member:dhcpproperties/ZG5zLm1lbWJlcl9kaGNwX3Byb3BlcnRpZXMkMQ:member1.localdomain",

 {"host_ref": "member:dhcpproperties/ZG5zLm1lbWJlcl9kaGNwX3Byb3BlcnRpZXMkMQ:member1.localdomain",

  "member_name": "member1.localdomain"}]

More Examples

There are more examples covered in the Multiple Object Body Feature using /request section in this guide.

These examples are part of the POSTMAN collection here and the Insomnia collection here.