Forum Discussion

Cole_McDonald's avatar
Cole_McDonald
Icon for Professor rankProfessor
6 years ago

Swagger Doc help adding a customProperty to a device

Can anyone translate the Swagger Doc into something I can understand?  I'm looking specifically at the device properties PUT or PATCH to try to figure out how to add a customProperty to a device.  Here's what I've got (PowerShell): 

        # Construct URL
        $resourcePath   = "/device/devices/2332/properties/CustomProperties"
        $url            = $URLRoot + $resourcePath

        $data = `
@"
{
    `"customProperties`" : [{
        `"name`"         : `"Failover.Cluster.ParentGUID`"               ,
        `"value`"        : `"$ClusterID`"
    }]
}
"@
        $response       = Send-Request  `
            -accesskey    $accessKey    `
            -accessid     $accessId     `
            -URL          $url          `
            -data         $data         `
            -httpVerb     "PUT"

 Send-Request handles all of the encryption and the invoke-restmethod {}

 

  • Joe_Tran's avatar
    Joe_Tran
    Icon for Advisor rankAdvisor
    6 years ago

    I don't typically use the /device/devices/{id}/properties/{name} endpoint but i would give the following a try:
      

        # Construct URL
        $resourcePath   = "/device/devices/2332/properties/Failover.Cluster.ParentGUID"
        $url            = $URLRoot + $resourcePath

        $data = `
@"
  {
        `"type`"         : `"custom`"                                    ,
        `"name`"         : `"Failover.Cluster.ParentGUID`"               ,
        `"value`"        : `"$ClusterID`"
  }
"@
        $response       = Send-Request  `
            -accesskey    $accessKey    `
            -accessid     $accessId     `
            -URL          $url          `
            -data         $data         `
            -httpVerb     "PUT"

    The type key might not be needed. The SwaggerDoc on this endpoint is weird. It literally says that the POST method is supported but all the keys in the model are readOnly?

     

     

  • Cole_McDonald's avatar
    Cole_McDonald
    Icon for Professor rankProfessor
    6 years ago

    Thank you Joe, looks like the JSON was the part I had wrong!  This worked for making the new property and populating it: 

            $resourcePath   = "/device/devices/2332/properties/"
        $url            = $URLRoot + $resourcePath

        $data = `
@"
{
        `"type`"         : `"custom`"                ,
        `"name`"         : `"Failover.Cluster.GUID`" ,
        `"value`"        : `"$ClusterID`"
    }]
}
"@
        $response       = Send-Request  `
            -accesskey    $accessKey    `
            -accessid     $accessId     `
            -URL          $url          `
            -data         $data         `
            -httpVerb     "POST"

     

  • Cole_McDonald's avatar
    Cole_McDonald
    Icon for Professor rankProfessor
    6 years ago
    1 hour ago, Sarah Terry said:

    @Cole McDonald @Joe Tran we will improve the documentation for this endpoint - thanks!

    Thank you.  The part I found confusing mostly was the example code given... it is just a generic, blank JSON block.  Had that had more detail, I'd have been able to figure it out more quickly.

    When I've done documentation for Functions and Objects in the past, I've always made sure to include expected input and output... not just types, but structural so that anyone can drop in on my code and be able to produce results immediately.  Most of what I've done in the past has been internal tooling, so I saw it as cost savings for the company I was working for due to reduced dev time.  I don't tend to see that level of documentation for APIs elsewhere.   All of MS's dev docs miss this as well.  I've commented on it and they've stated that it was a common complaint.  Their new documentation is much clearer, but most of their offerings are still the old documentation style; just giving the function names and leaving it to the developer to parse their meaning/usage.