Cisco ASAv firewall REST API: Bulk Requests

Introduction

Continuing on the same track with ASA REST API we are going to explore how to be more efficient when firing up the json code toward our firewalls. In previous example we created a small number of service and network objects and groups, today we are going to experiment with larger number of objects created by smaller number of calls. Lets get the ball rolling.

Bulk service object creation

To create a bulk request we need to adjust some parameters such as API endpoint URL. As you recall, when we created a new service object we were pointing to this URL: https://<management-ip>/api/objects/networkservices.

Now we are going to redesign the call a little bit and will always point to same endpoint regardless of object type. We will simply use https://<management-ip>/api and the more specific resource URI will be part request body. This allows us for example create bulk of service and network objects in one call.

[
  {
    "resourceUri": "/api/objects/networkservices",
    "data": {     
  "kind": "object#TcpUdpServiceObj",
  "name": "TCP-21",
  "value": "tcp/21"
}, "method": "Post" }, { "resourceUri": "/api/objects/networkservices",    "data": {
  "kind": "object#TcpUdpServiceObj",
  "name": "TCP-22",
  "value": "tcp/22"
}, "method": "Post" }, { "resourceUri": "/api/objects/networkservices",    "data": {
  "kind": "object#TcpUdpServiceObj",
  "name": "TCP-23",
  "value": "tcp/23"
}, "method": "Post" }, { "resourceUri": "/api/objects/networkservices", "data": {
  "kind": "object#TcpUdpServiceObj",
  "name": "TCP-24",
  "value": "tcp/24"
}, "method": "Post" }
]

If everything is hunky dory you will receive a Status Code 200 OK and response body will contain additional details.

{
"entryMessages":
[
     {
     "resourceUri":"/api/objects/networkservices",
     "method":"POST",
     "selfLink":"http://10.201.230.5/api/objects/networkservices/TCP-21",
     "messages":
     [
         {
         "level":"Info",
         "code":"201",
         "details":"Created (201) - The request has been fulfilled and resulted in a new resource being created"
          }
     ]
     },
     {
     "resourceUri":"/api/objects/networkservices",
     "method":"POST",
     "selfLink":"http://10.201.230.5/api/objects/networkservices/TCP-22",
     "messages":
     [
         {
         "level":"Info",
         "code":"201",
         "details":"Created (201) - The request has been fulfilled and resulted in a new resource being created"
         }
     ]
     },
     {
     "resourceUri":"/api/objects/networkservices",
     "method":"POST",
     "selfLink":"http://10.201.230.5/api/objects/networkservices/TCP-23",
     "messages":
     [
         {
         "level":"Info",
         "code":"201",
         "details":"Created (201) - The request has been fulfilled and resulted in a new resource being created"
         }
     ]
     },
     {
     "resourceUri":"/api/objects/networkservices",
     "method":"POST",
     "selfLink":"http://10.201.230.5/api/objects/networkservices/TCP-24",
     "messages":
     [
         {
         "level":"Info",
         "code":"201",
         "details":"Created (201) - The request has been fulfilled and resulted in a new resource being created"
         }
     ]
     }
],
"commonMessages":[]
}

Ideally your deployment script would examine the response and capture the self links that can be used to un-deploy this call. Also the message details are important to verify if objects were successfully created.

Now we are going to look at error handling by creating another request that will have one already existing object and one new in it.

[
  {
    "resourceUri": "/api/objects/networkservices",
    "data": {     
  "kind": "object#TcpUdpServiceObj",
  "name": "TCP-24",
  "value": "tcp/24"
}, "method": "Post" }, { "resourceUri": "/api/objects/networkservices", "data": {
  "kind": "object#TcpUdpServiceObj",
  "name": "TCP-25",
  "value": "tcp/25"
}, "method": "Post" }
]

The response header will contain 400 Bad Request status code and body will reveal some clues.

{
"entryMessages":
[
     {
     "resourceUri":"/api/objects/networkservices",
     "method":"POST",
     "messages":
     [
         {
         "level":"Error",
         "code":"DUPLICATE",
         "context":"objectId",
         "details":"TCP-24"
         }
     ]
     },
     {
     "resourceUri":"/api/objects/networkservices",
     "method":"POST"
     }
],
"commonMessages":[]
}

The result result is that even the second object did not exists it was not created. When you reverse the object order in request, it will not help either. This means that the entire request need to create unique objects otherwise it will fail. So watch for return codes.

I have tried to create 103 unique objects in one request and I have found that the upper limit for single request is 100 entries.

{
"commonMessages":
[
     {
     "level":"Error",
     "code":"MAX-ENTRIES-LIMIT-EXCEEDED",
     "details":"The number of entries found are, 103. The bulk entries limit:100"
     }
]
}

Lets go back to our first four service objects and undeploy them using four unique DELETE Requests. The resource URIs are as follows:

Note: So far I have not found way of performing multiple object removal in single request. It seems that bulk operation only supports POST method toward service objects at the moment. The following below did not work.

[
  {
    "resourceUri": "/api/objects/networkservices/TCP-21",
    "method": "Delete"
  },
  {
    "resourceUri": "/api/objects/networkservices/TCP-21",
    "method": "Delete"
  }
]

Response had status code 400 Bad Request even if those URI are indeed valid and you can query them with GET request.

{
"entryMessages":
[
     {
     "resourceUri":"/api/objects/networkservices/TCP-21",
     "method":"DELETE",
     "messages":
     [
         {
         "level":"Error",
         "code":"INVALID-INPUT",
         "details":"Invalid resourceUri:/api/objects/networkservices/TCP-21"
         }
     ]
     },
     {
     "resourceUri":"/api/objects/networkservices/TCP-21",
     "method":"DELETE",
     "messages":
     [
         {
         "level":"Error",
         "code":"INVALID-INPUT",
         "details":"Invalid resourceUri:/api/objects/networkservices/TCP-21"
         }
     ]
     }
],
"commonMessages":[]
}

The 100 objects limitations also affect how are the responses constructed. When you query the following resource https://<management-ip>/api/objects/networkservices you will see that the body contains only 100 items even if 110 exists. You can see this by examining the offset, limit and total fields on body.

{
   "kind": "collection#NetworkServiceObjects",
   "selfLink": "https://10.201.230.5/api/objects/networkservices",
   "rangeInfo":
   {
       "offset": 0,
       "limit": 100,
       "total": 110
   },

Funny enough, the list will not start with the first configure service objects, but started from TCP-100 up till TCP-200. To see other items you need to manipulate the offset value. We can demonstrate this using API Console at documentation page.

rest-api-offset

Now the item list will start from TCP-110 and will include our older objects such as TCP-21, TCP-22 etc. You can also play with the limit parameter to constrain number of returned objects. If you look at Inspector, you will see the request parameters have been modified to include our query parameters.

rest-api-offset-body

Conclusion

Bulk object creation and retrieval handling should help you build more efficient communication patters between the firewall and automation tool or network controller.

Advertisements

One thought on “Cisco ASAv firewall REST API: Bulk Requests

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s