Mango API POST /rest/v2/point-values - Import Point Values

[MattFox]

Hi All, trying to import information from other sources en masse. However, I am struggling to understand the swagger docs...
The model example shows no instance of where the points value should be put, let alone the correct format...
All the documentation shows me here is

[
  {
    "data": {},
    "editPermission": "string",
    "folderIds": [
      0
    ],
    "id": 0,
    "modelType": "NUMERIC",
    "name": "string",
    "params": [
      {
        "label": "string",
        "name": "string",
        "options": {},
        "type": "string"
      }
    ]
    "validationMessages": [
      {
        "level": "INFORMATION",
        "message": {
          "args": [
            {}
          ],
          "key": "string"
        },
        "property": "string"
      }
    ],
    "xid": "string"
  }
]

Looks more like a datapoint model excerpt rather than point value information here...

Thanks!

[phildunlap]

Hi Fox,

Yeah, the swagger documentation is automatically generated so it's not always clear / to the point. Here's a list with one item that can be POSTed to the /rest/v2/point-values endpoint:

[
  {
    "xid": "DP_XID",
    "dataType": "NUMERIC",
    "value": 123.456,
    "time": 1568036880907,
    "annotation": null
  }
]

[MattFox]

Many thanks Phil, you'll see a lot of the docs have the same exact model in them. Is it something that can be easily rectified?

Fox

[phildunlap]

There's not been a ton of time put into ensuring the swagger models are good / useful. We advise people to use the GETs to get examples of the models if they're trying out a new endpoint. Of course, that wouldn't have helped here because the point value endpoints let you choose what fields you would like returned. I have opened this git issue: https://github.com/infiniteautomation/ma-modules-public/issues/72

[terrypacker]

@MattFox just letting you know I've tried in the past to fix this but didn't have much luck. But I tried again today and managed to make an improvement. There are likely other models that will suffer from this problem so when Mango 3.7.0 is released if you see any more of these types of problems please let us know.

Here is the git issue if you are interested in following:

https://github.com/infiniteautomation/ma-modules-public/issues/72

[MattFox]

Thanks gentlemen, hugely appreciated.
Rather than wait for 3.7 (I'm still on 3.5.6 due to it being a production server and 3.6 has fair number of alterations), would it be asking too much for a copy of all the required model data for the APIs?
Just as a means to refer to as I doubt I'll be stopping here with the API. Longterm goal is to bring everything outside of mango and fully rely on the API to do all my data handling

Fox

[phildunlap]

It would not be so simple. If the annotations aren't generating the models properly (although Terry did close the git issue he opened) then it'd be constructed by hand or examples within Mango would have to be recorded somewhere. It is easier to respond piecemeal for specific endpoints and fix model generation in later versions on endpoints where it isn't working.

[terrypacker]

@MattFox our swagger based documentation is pretty rough, there are tools that can be used to generated HTML/PDF/etc. docs from it but I have yet to find one that will produce enough meaningful output. I might take another look at this in the near future as it was at least 6 months ago that I attempted this. I'm not sure how much you know about the swagger spec, but the theory is that Mango has an endpoint which by default is at

swagger/v2/api-docs

that will generate JSON which describes all the endpoints and their models. That JSON can be used in various tools to produce documentation on the API.

The git issue that was closed was because the task was too overwhelming and not high enough priority. I would suggest that you take a look at https://github.com/swagger-api/swagger-codegen and see if you can run that against the version of Mango you want documentation for. You might be able to tweak the settings enough to get what you want. That tool can output client/server code and also documentation in various formats.

[MattFox]

@terrypacker said in Mango API POST /rest/v2/point-values - Import Point Values:

The git issue that was closed was because the task was too overwhelming and not high enough priority.

Apologies Terry, I was unaware what a cluster#$%^ this was. Thank you for your assistance with this, I'll get onto to having a read and will see if I can be of some assistance

Fox