API Documentation

[hacki11]

From several projects in the past i had to create/use rest api endpoints.
The most important thing was a good API documentation, even more when the target is not available for "trial and error".

There is a standard called OpenAPI where a HTTP API can be specified with json or yaml.

I see the following benefits:

• State of the art documentation
• Specification supports versioning/deprecation marker
• Easier/more structured as in PDFs
• Example models provided
• Generating Client libraries for every common language!
• Generating Mockserver for testing purpose of client applications!
• Try-Out Mode in Web UI for fast start
• Yaml/Json file is under version control
• Export documentation to PDF
• Directly update docu within the code change PR
• More

I have already started with a few endpoints with the data models and example values to give you a first impression. Here you see JI, JV, JQ, JK, JS as a first draft.

You can see very quickly what endpoints are available, what information you get, what you have to provide as a user.
This also avoids more questions regarding which endpoint for what (like i had).

This should not be negative critics to @1coderookie, absolutely not. The documentation you did in the manual are really great and can not be found in many open source projects. But i think for the new release it is a great possibility to go the next step towards professional api documentation.

#268
#237

[1coderookie]

You are talking about the JSON-API-documentation and not about the whole manual, right? In that case I think it's a great idea - but unfortunately I have to tell you that I won't be able to do that. :(
I neither have the knowledge about this whole JSON-API-stuff (and having hard times with the description of that stuff already ;) ) and the mentioned doc-solution nor the time to get into it.
Because you already started with that - would you be willing to do that? I'd be happy if you would do so, then I could also get rid of that JSON-chapter within my manuals which I'm not happy with anyway. I'd just set a link to that new JSON-documentation in that chapter instead and keep on listing the available JSON-commands within chap. 8.1 with a short description as it already is.
It would be even more better if you could do that, cuz you are the maintainer of the ioBroker-plugin and you are already using that JSON-stuff, so I guess you would also realize if any function doesn't work the way it should or if any function is probably missing.

[fredlcore]

I also think that this is part of the technichal documentation, not the user manual. In the end it would land on my plate which is already quite full in that regard, so this is something where "external" help would be really helpful. We set up a dedicated document for that in my repository to which you or whoever would/could do it have access to. Other than that, I don't see how we could do it at the moment.

[hacki11]

I'm just talking about the JSON-API-documentation, right.
I'm happy to take that work on my side, but i will have some questions regarding the endpoints. (i do not have a device to play around with the new version, yet).

I'm not sure if i got everything, but i documented everything from the manual.
It would be a great help if someone can review the documentation, data models and example values (in prosa, not the yaml code itself)

https://app.swaggerhub.com/apis/hacki11/BSB-LAN/2.0

After review and fixed findings i will provide a PR.

[1coderookie]

Great, thanks a lot @hacki11!
Please let me know when you're done and where I should link to from my manuals then.

[fredlcore]

Yes, thanks - the thing is that I don't work with YAML, so I can't really tell if your findigs are accurate or not, but if you have questions, me and @dukess will certainly/hopefully be able to answer them.

[hacki11]

There is no need to go through the yaml file for you as reviewer. Just click through the interactive documentation on the Right side and check input and output parameter Schemas and their example values. Just ignore the yaml, i will care about it. :)

[fredlcore]

Ok, will try :)!

[fredlcore]

In conjunction with the upcoming release of BSB-LAN 2.0, here comes a list of changes over the last months that could/should be reflected in the API documentation:

• New command /JB: Export a list of all writeable parameters of the heating system as JSON structure. Takes no parameters. Can be used in conjunction with /JS to (selectively) write back values as JSON structure is the same. Use at your own risk!
• Schema Parameter now has new attributes dataType_name (such as VT_TEMP), dataType_family (such as DT_VALS), precision(characters after decimal dot) and readwrite: 0 - read/write, 1 - read only, 2 - write only. Attribute readonly is still kept for now but is going to be deprecated.
• Schema PossibleValue now has new attributeisswitch: 0 - Any type, 1 - ONOFF or YESNO type
• Schema Error now has additional new parameter values; complete list is now: 0 - ok, 7 - parameter not supported, 1-255 - LPB/BSB bus errors, 256 - decoding error, 257 - unknown command, 258 - not found, 259 - no enum str, 260 - unknown type, 261 - query failed, 262 - Too few/many arguments in SET command

I hope I haven't forgotten anything, @dukess?
@hacki11, is this the information you need to update the API reference?

[dukess]

/JI was changed: "hardware", "onewirebus", "onewiresensors", "logvalues", "loginterval" fields added, "logged" array added, "protectedGPIO" array removed.

[1coderookie]

@hacki11
Did you see this? I just had a look athe the swagger docu and only checked the /JI there, at least that one is still the old description:

{
  "name": "BSB-LAN",
  "version": "1.1.21-20200904085757",
  "freeram": 2659,
  "uptime": 276959150,
  "MAC": "DE:AD:BE:EF::CA:FE",
  "freespace": 0,
  "bus": "BSB",
  "buswritable": 1,
  "busaddr": 66,
  "busdest": 0,
  "monitor": 0,
  "verbose": 1,
  "protectedGPIO": [
    {
      "pin": 10
    },
    {
      "pin": 11
    },
    {
      "pin": 12
    }
  ],
  "averages": [
    {
      "parameter": 700
    },
    {
      "parameter": 701
    }
  ]
}

There's also the v1.1 mentioned, we recently released v2.0 as the latest stable version, so maybe you want to update the docu accordingly..?

[hacki11]

It is for sure far too late for my 2 cents but i have a question regarding /JB.

Normally on list of parameters you stick to

{
  "<ParameterID>": {
    "value": ...,
    "whatever": ...
  },
  "<ParameterID2>": {
    "value":...
  }
}

But with /JB we now have

{
  { 
    "parameter": "<ParameterID>": {
      "value": ...,
      "whatever": ...
    },
    {
      "parameter: "<ParameterID2>": {
        "value":...
    }
}

Going with the first would be consequent i think.

More important is the fact, that currently it is not valid json.
copy this to a json validator:

{
{"Parameter":"70", "Value":"4.2", "Type":"1"},
{"Parameter":"130", "Value":"65535", "Type":"1"},
}

https://jsononline.net/json-validator

A map {} needs a key for an entry. If you want to stick without key it needs to be an array []. I think this should be fixed to produce correct json.
Furthermore the property names are normally lower camel case (value) but here it is upper camel case (Value).

[fredlcore]

Thanks, @hacki11!
@dukess, since you wrote the code for /JB and /JS, do you think that these changes could be implemented without much effort?

[dukess]

Hi, thank you!
This is a legacy caused by the lack of memory on Mega and the need for compatibility with the old /JS command format.
I'll try adding the keys to /JB (line 5740 in BSB_LAN.ino). I hope I won't have to whole rewrite the JSON handler (lines 5753-5852). :)

[fredlcore]

@dukess, thanks for the quick fix! @hacki11, could you check if the current master repo version meets the requirements? Thanks!

[dukess]

By the way, /JS allow to set multiple parameters per time. Ex: we can feed /JB output to /JS.

[hacki11]

Works perfectly!

[hacki11]

Schema Parameter now has new attributes dataType_name (such as VT_TEMP), dataType_family (such as DT_VALS), precision(characters after decimal dot)

Schema: i would have expected VT_* but at least on my system (2.1) VT_ prefix is always missing. I only see "TEMP", "ENUM", etc. is the example in the brackets wrong or the returned information?

precision: I get e.g. 0.1 => you wrote "characters after the decimal dot". that would mean 0.1 characters what is of course impossible. Wouldn't be 1 correct?

[fredlcore]

Schema: Yes, my example was wrong, the returned information is stripped of the "VT_" prefix. It could be easily added, but the question is whether this is really necessary as it consumes extra memory. External systems using this information don't know about the internal naming convention of BSB-LAN, so I would think coherence with the BSB-LAN code is not necessary. If you think otherwise, it is however no big deal to adjust this.

Precision: Again my mistake, there is no 0.1, but only 0, 1, 2 etc.

[hacki11]

so this will also be fixed in code i assume?

[hacki11]

I think the current meaning is "lowest positive number". For 720 i get 0.01 and would make sense.

[fredlcore]

Sorry, my mistake again. Precision is stored in optbl[] as 0, 1, 2 etc. as in the number or digits after the decimal point (that's where I based the description above on), but this is returned as 0.1, 0.01 or 0.001 respectively when querying the JSON.

[hacki11]

Schema PossibleValue now has new attributeisswitch: 0 - Any type, 1 - ONOFF or YESNO type

{
  "1603": {
    "name": "Manueller TWW-Push",
    "dataType_name": "ONOFF",
    "dataType_family": "ENUM",
    "possibleValues": [
      {
        "enumValue": 0,
        "desc": "Aus"
      },
      {
        "enumValue": 1,
        "desc": "Ein"
      }
    ],
    "isswitch": 1,
    "dataType": 1,
    "readonly": 0,
    "readwrite": 2,
    "unit": ""
  }
}

where do i find the isswitch property in possibleValues?

[fredlcore]

Strange, I thought I had answered here earlier already, but my answer doesn't show up here, so again:
isswitch is a flag to make it easier for externals systems to decide whether to display a dropdown or a switch. Technically, VT_ONOFF, VT_YESNO etc. are just ENUMs with two (opposing) entries that are displayed in BSB-LAN in the same way as other options are displayd, i.e. as dropdowns. Other systems may want to display a radio button or something like that after evaluating isswitch.

[hacki11]

Yes, that's clear and it is available. But what I don't see is why it should be inside possiblevalues. At least currently it isn't there. Should it be?

[dukess]

This is an error in the description. The "isswitch" field belongs to the program, not "PossibleValues"

[hacki11]

I have added the changes here https://app.swaggerhub.com/apis/hacki11/BSB-LAN/2.1
Only the open topics are missing now (JB is still not complete because of invalid JSON)

[1coderookie]

Great, thanks!
Will you link this updated version to the 'original' URL (https://raw.githubusercontent.com/fredlcore/bsb_lan/master/openapi.yaml) which is mentioned within the manual right now, or should I change the link in the manual to the abovementioned one (https://app.swaggerhub.com/apis/hacki11/BSB-LAN/2.1)?
Or will you take care of the missing topics first before changing it to the 'original' URL?

[hacki11]

I will provide a PR after all topics are fixed. I wanted you to be able to have a look on the current progress

[1coderookie]

Great, thanks! :)

[fredlcore]

I'm closing this here as we have another discussion thread here:
#258