Swagger API V2 documentation Moderators: adafruit_support_bill, adafruit

[BrynHLewis]

Hi all,

I'm using the swagger definitions to generate a C# client (using nswagstudio) and the deserialisation of responses is blowing up with an exception which is basically the "id" is not valid.

Code: Select all | TOGGLE FULL SIZE

if (status_ == "200")
{
   var responseData_ = await response_.Content.ReadAsStringAsync().ConfigureAwait(false);
   var result_ = default(Data);
   try
   {
      result_ = Newtonsoft.Json.JsonConvert.DeserializeObject<Data>(responseData_, _settings.Value);
      return result_;
   }
   catch (System.Exception exception_)
   {
      throw new SwaggerException("Could not deserialize the response body.", status_, responseData_, headers_, exception_);
   }
}


If I look at the response payload

"{\"id\":\"0DRTNY0EBWPW9G1SHNV641B06C\",\"value\":\"1.23\",\"feed_id\":745760,\"feed_key\":null,\"created_at\":\"2017-12-31T04:17:08Z\",\"location\":null,\"lat\":null,\"lon\":null,\"ele\":null,\"created_epoch\":1514693828,\"expiration\":\"2018-01-30T04:17:08Z\"}"

and then compare with the response definition

Code: Select all | TOGGLE FULL SIZE

"Data": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "number",
                    "readOnly": true
                },
                "value": {
                    "type": "string"
                },
                "feed_id": {
                    "type": "number"
                },
                "group_id": {
                    "readOnly": true,
                    "type": "number"
                },
                "expiration": {
                    "type": "string"
                },
                "lat": {
                    "type": "number"
                },
                "lon": {
                    "type": "number"
                },
                "ele": {
                    "type": "number"
                },
                "completed_at": {
                    "readOnly": true,
                    "type": "string"
                },
                "created_at": {
                    "readOnly": true,
                    "type": "string"
                },
                "updated_at": {
                    "readOnly": true,
                    "type": "string"
                },
                "created_epoch": {
                    "readOnly": true,
                    "type": "number"
                }
            }
        }


It looks like "id" is expected to be a number but "0DRTNY0EBWPW9G1SHNV641B06C" doesn't look like a number to me.

I have a modified local copy of the definition file (changed id to a string) and my client appears to work ok for my CreateData call, but I haven't tried any others.

What am I missing?

Thanks

@KiwiBryn
blog.devmobile.co.nz

[abachman]

Hi Byrn!


You are correct, that's a bug, thank you for reaching out! That is an error in the API docs, not in the API itself. I've updated the v1 and v2 JSON files in the https://github.com/adafruit/io-api project.

We use that project internally with the javascript Adafruit IO client that powers the io.adafruit.com UI, but it's extremely permissive with regards to data types and type checking, which is probably why we haven't noticed it before now.

Also, I am very curious what kind of project you have in mind and how you useful you find the swagger generated client to be. We provide the documentation so that folks can do stuff just like this, but I've always suspected it would take some massaging to auto-generated code play nice with real-world projects. Are you working on pure server-side stuff or is this going to be .NET code running on a smart device somewhere?


- adam

[BrynHLewis]

Hi Adam,

Still broken :-(

You fixed Data (used by CreateDataAsync)

For my project I also need to fix DataResponse (used by CreateGroupDataAsync)

There maybe other places I haven't found yet...

I'm working on two Windows10 IoT Core based field gateways so "cheap n cheerful" *duino devices can connect to Adafruit.IO over nRF24L01 or LoRa wireless links.

Thanks
@KiwiBryn
blog.devmobile.co.nz

[abachman]

Ah yes, I see it. Fixed that one too.

I don't see any other places where Data record IDs are mentioned but typed incorrectly. URL ID params are all typed string regardless of whether the system expects strings or numbers, hopefully that won't be a problem when dealing with other record types.

Also, anytime you hit an error like this with the docs, it's very possible we're delayed in updating them. Feel free to send a pull request on Github if you find and patch something. We are open to contributions.

I'm working on two Windows10 IoT Core based field gateways

Oh nice! I haven't used Windows in a bit, but they seem to be pretty sensible about their current approach to the kind of open source and low powered systems that IoT favors. So is this something like Raspberry Pi's listening for updates from other pieces of hardware and forwarding the data on to IO?


- adam