4 Replies Latest reply on May 22, 2018 1:39 AM by kwongheng

    NSX REST API put request body for routing/config

    kwongheng Lurker

      Hi all,


      In NSX vSphere API Guide 6.2 page 142 for Configure Routes, we know that we need to submit the entire request body when perform changes via REST API PUT. This means the entire routing configuration is submitted even if I only need to make 1 small change




      The request body contains <password> element for bgb neighbour. Do we need to specify the passwords when submitting even though the password has not changed? Can this element be omitted? If omitted will i clear my bgp neighbour password instead?


      Attached shows the XML element that I am referring to


      Thanks for any help

      Kelvin wong

        • 1. Re: NSX REST API put request body for routing/config
          canero Hot Shot

          In general, POST is used for creation of objects, while PUT is used for modifying a single object. But even a single object to be modified, some other fields could be mandatory. Since it is described as optional besides the field with arrows  it should work without entering this element.


          This link  a similar example about changing the Controller syslog host, and it is about the API command syntax, where sometimes clearly documenting optional fields, and sometimes not explaining wheteher every field is optional or mandatory:


          Rest API Post and Put Difference


          So, with PUT command changing or updating a single BGP neighbour may/may not need some mandatory values, so could be tested first successfully updating with whole structure, and after same PUT command, but this time a single field is removed


          NSX Manager debug logging also shows about missing values, if during testing it gives missing value error, this may show this is a mandatory field, even would stay same without changing along the neighbor Ip address.



          • 2. Re: NSX REST API put request body for routing/config
            kwongheng Lurker

            Thanks for the reply.. however, I would say that a PUT in NSX is not for a single object only. What I did was created an xml with all the minimum required fields and only one neighbour because that was where I wanted the change to be. Unfortunately, that executed successfully and wiped out all the other routing configuration in the Edge that were not in the XML!


            So it seems like even for a PUT on a single object in NSX, you are required to submit the entire routing configuration in XML, missing anything will mean those settings are blanked out. Which is why I asked the question about the passwords

            • 3. Re: NSX REST API put request body for routing/config
              canero Hot Shot

              Here resource, optional  and field terms seems to create misunderstanding. All of the representation of the resource appears  needs to be updated, although optional appears "not need to be specified", with PUT command it takes all of the unspecified optional fields to default value. (which means erasing the configuration previously created.)


              PATCH command provides partial updates to a specific field, could not find  on PATCH on NSX Edge to update a single BGP neighbor or whether PATCH is supported on current NSX API, there are not specific examples about usage of PATCH for specific tasks done through REST API calls to NSX Manager.


              These links could be helpful about:



              Read the Docs has a clever little blurb on PUT vs PATCH. Both methods are shown to “update a resource” in the semantics chart. The difference? PUT updates the entire resource while PATCH updates only the resources fields provided in the call. With PUT, I need to provide data for every field that the resource contains, otherwise the missing fields are set to null or the request fails. These are annoyances I’ve hit with the VMware NSX API on a number of occasions when wanting to update specific fields contained within an NSX Edge resource. The PATCH method sounds useful for updating one of a resource’s fields, such as the password field, without having to first GET all of the other fields.







              So, based on RFC 7231, PUT should be used only for complete replacement of a representation, in an idempotent operation. PATCH should be used for partial updates, that aren't required to be idempotent, but it's a good to make them idempotent by requiring a precondition or validating the current state before applying the diff. If you need to do non-idempotent updates, partial or not, use POST. Simple. Everyone using your API who knows how PUT and PATCH works expects them to work that way, and you don't have to document or explain what the methods should do for a given resource. You're free to make PUT act in any other way you see fit, but then you'll have to document that for your clients, and you'll have to find another buzzword for your API, because that's not RESTful.



              The HTTP PATCH method should be used whenever you would like to change or update just a small part of the state of the resource. You should use the PUT method only when you would like to replace the resource in its entirety. Note that PATCH is not a replacement for PUT or POST, but just a way of applying a delta update to a resource representation. Roy Fielding, who authored the REST architectural style and many web standards, said that he created PATCH because “partial PUT is never RESTful.”



              • 4. Re: NSX REST API put request body for routing/config
                kwongheng Lurker

                Thanks for the reply, so back to my original question about BGP neighbour password field. Even though it's "optional" I guess if I have no choice but to use PUT (since PATCH is a no-go), I must specify the password to avoid it blanking out with the update.