vManage APIs & REST

Hello, everyone.

I was planning to include this under the Device Programmability lesson since it covers APIs, RESTCONF, NETCONF, etc, but I actually have rather long questions about every individual protocol and having it all in 1 post would be hard to read and very long, so I decided to separate them this way.

When sending API calls to SD-WAN vManage, the entire process is a bit weird. To summarize, the following needs to be done:

  1. You must log in with username and password (specified as j_username and j_password) and send a POST request to the vManage under /j_security_check. This will generate a JSESSION ID as a cookie
  2. With this Session ID/cookie, you must generate a CSRF token (to prevent cross-site request forgeries, out of scope for ENCOR).
  3. Include this token in your further requests and you can now access the API and retrieve information

Here are my questions:

  1. The documentation states that the POST request for the cookie/session ID must have the data/form set to x-www-form-urlencoded What does this mean? Postman has several options for us to use to specify the data, but the form mentioned above always has to be selected otherwise the request won’t work. What exactly is www-form-urlencoded?
  2. We can either manually (or Postman can do this for us) specify the Content-Type which is the type of data that we’re sending to the resource.

    Is this important? In Python, the request again wouldn’t be processed if I didn’t specify this. Can’t the destination resource just read the data and determine whether its JSON, XML, etc?

Thank you.
David

Hello David

The application/x-www-form-urlencoded format encodes form data as key-value pairs separated by &, with spaces replaced by + and special characters percent-encoded. For example:

j_username=admin&j_password=Secret123

This format is mandatory for vManage’s /j_security_check endpoint because the server-side authentication handler expects parameters in this specific encoding. Any alternative formats like JSON/XML would be rejected as malformed requests.

So it is simply the “language” or the syntax that the device understands, and this has been standardized.

While some APIs do auto-detect content types, vManage requires explicit headers. This is because the authentication endpoint /j_security_check uses legacy form handling that requires Content-Type: application/x-www-form-urlencoded.

As shown in Postman screenshots and Python examples, omitting these headers causes failures because vManage’s API doesn’t perform content negotiation - it strictly validates the stated Content-Type against expected values for each endpoint. It’s simply a matter of design. Could it (or should it) have been designed differently? Maybe, probably, but it wasn’t… :stuck_out_tongue:

I hope this has been helpful!

Laz