• 0
Cole McDonald

Swagger Doc help adding a customProperty to a device

Question

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 {}

 

Share this post


Link to post
Share on other sites

5 answers to this question

Recommended Posts

  • 0

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?

 

 

Share this post


Link to post
Share on other sites
  • 0

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"

 

Share this post


Link to post
Share on other sites
  • 0
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.

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now