Ver 3.7.0 web tag API

[mcrossley]

The tag processor API means that you no longer have to generate files to use web tags, you can request web tags values on demand. Obviously this creates an overhead on Cumulus so use this feature wisely.

There are two methods of calling the new API (note the tag names are case sensitive just like normal):

HTTP GET
This provides a quick and simple method of getting data, you just provide the web tag names in the GET URL and MX returns a simple JSON string with the tag-name:tag-value pairs.
The tags are always returned with the default format. You can specify a special parameter "rc" (which must be the first URL parameter) to apply the usual remove commas format to all the tags.

eg.
http: //localhost:8998/api/tags/process.json?temp&hum&dew
or
http: //localhost:8998/api/tags/process.json?rc&temp&hum&dew

Which will return the following format string in the body...

Code: Select all

{"temp":"15.8","hum":"73","dew":"10.5"}

Note, ALL values are quoted as strings as it is difficult to know which are numeric and which are not.



HTTP POST
The POST method allows you to put whatever text you like in the request body - and include any web tags plus formatting you wish. The string returned will be exactly the same text with the tags substituted with data.
So you could send a simple comma separated list, or some JSON text, or XML, whatever.

eg.
http: //localhost:8998/api/tags/process.txt

With a POST body text of..

Code: Select all

<#time format="yy/MM/dd hh:mm:ss">,<#temp>,<#RecentFeelsLike d=1>

would return...

Code: Select all

20/07/14 01:48:11,15.7,18.4

Another example

Code: Select all

{
    "DateTime:"<#time format="yy/MM/dd hh:mm:ss">",
    "OutsideTemp":<#temp>,
    "FeelsLikeYest":<#RecentFeelsLike d=1>
}

would return...

Code: Select all

{
    "DateTime:"20/07/14 01:50:56",
    "OutsideTemp":15.7,
    "FeelsLikeYest":18.4
}

Have fun!

[HansR]

Working fine and smooth! Thanks, great addition.
(can be set resolved in the Suggestions Thread)

[water01]

OK I will be the one to ask the dumb question.

I get how you do this but doesn't this mean I have to allow access from my website to my router and then port forward it to CumulusMX computer?

[mcrossley]

OK I will be the one to ask the dumb question.

I get how you do this but doesn't this mean I have to allow access from my website to my router and then port forward it to CumulusMX computer?

If you wanted to use it from a remote web server, yes. But not recommended for the obvious reason that the API interface is not secure.

It is meant for services either on the same computer as Cumulus or on your local network.

[water01]

OK that's what I thought, so dumb question number two what is this useful for? IOT?

[HansR]

If I may answer that last question as requester of this feature.

If I am not thinking about realtime (that would require direct access from the website to Cumulus as you just discussed with Mark), but about history data, especially aggregated data or just informational data, it sometimes is easier to get them through direct communication. As my CumulusUtils avoids any type of file processing by Cumulus it was very difficult e.g. to get the version information or Davis info. Now I can handle it all at runtime, no more processing required.

All I need to do now is look what more info CMX has in store.

[freddie]

You can expose the API to the internet via reverse proxying. I do this with my trends graphs on my external website, plus many of my pages and data files are hosted and generated internally and are proxied using the same mechanism. I don't send any data to my external site - it is all pulled. Obviously you have to do this carefully.

Advantages: no regular data transfer that takes up bandwidth (that may never be accessed by anybody). Exposure of only defined data and API calls.
Disadvantages: it leaves you open to DOS if your website is too popular (mine isn't ). Misconfiguration may expose more of your internal functions than you think! If your internet link goes down then your proxied calls will not work (return 502/503 codes) - but if your internet link is down then your external website won't be up-to-date anyway. Swings and roundabouts.

[sfws]

I have today replaced 3 api get calls I had in a script (it was making a novel use of api used by an admin interface page for another purpose) by one api call using the new get functionality. I was staggered by how easy it was to implement this new feature that I documented in Wiki yesterday (dodging Mark's updates of same page). But the main joy was that it greatly simplified my script making many script lines and variables redundant. So thank you Mark for implementing this.

I do this with my trends graphs on my external website

Is that why your trends page is showing beta 2 "powered by Cumulusv3.7.0-beta2 (3089)" whilst your other pages are showing beta 3 "powered by Cumulus v3.7.0-beta3 (3089)"?

I can understand you might not had time to update from beta to public release, but I struggle to understand how you could use a different MX for just one page.

[freddie]

I do this with my trends graphs on my external website

Is that why your trends page is showing beta 2 "powered by Cumulusv3.7.0-beta2 (3089)" whilst your other pages are showing beta 3 "powered by Cumulus v3.7.0-beta3 (3089)"?

I can understand you might not had time to update from beta to public release, but I struggle to understand how you could use a different MX for just one page.

The version and build numbers on that one page are static, and I either have to make them dynamic or remember to update them when I update MX. I haven't done either as yet