Rules API - Documentation v Reality

Developer Programs Rules API
1

I’ve been moving stuff into the Rules API. My remaining Automations largely involve either setting Security Modes or sending notifications.

Although lacking some important fine detail (like failing to mention that Security Modes appear in ‘PascalCase’, rather than ‘camelCase’ as they are in the capability and as is the usual ST convention), the Rules API Reference does at least suggest how to use the Security Mode in a condition. It makes no mention of the setting the Security Modes in an action. By contrast the Core SDK seems to be interested in ‘armState’ which doesn’t appear in the Reference, but omits much of the other location stuff that is there.

There are no mentions of sending notifications at all.

However if the Automations have been migrated to the Rules API, surely that means both are actually supported?

The Rules API is moving into the prime time now, so it would help greatly if there was consistency over how it is documented.

The same really applies across the board. I can pull notifications and device history out of the API should I want to and yet there isn’t a sniff of them in the Reference. I am not expecting direct access to the API (Postman, curl etc), the SDK and CLI to be in perfect harmony as the CLI depends on the SDK which depends on the API. There is a natural order there though. The API Reference needs to document anything that is live, proposed, deprecated or dead in the API, as is done for capabilities. Those should equate to ‘works unless something has broken’, ‘your mileage may vary’, ‘lingering like a bad smell’, and ‘too late’. Once you have that sorted the rest should be able to follow naturally.

I also noted the old SDC.webcore.co proof of concept claimed to handle ‘changes’ type conditions. I didn’t test that live but rather assumed that isn’t really the case as anything that major and that old would have to be mentioned somewhere.

2 Likes
2

Forgot to mention buttons. It isn’t clear how they are handled in the Rules API but it seems they must be as I have Quick Controls handling them.

The button attribute is only meaningful when an event has just happened, and it doesn’t clear to standby, despite what the app makes it look like. So neither equals or any implementation of changes would be appropriate. webCoRE implements this special case as ‘gets’.

3

[quote=“orangebucket Prepaid Gift Balance”]
I’ve been moving stuff into the Rules API. My remaining Automations largely involve either setting Security Modes or sending notifications.

Although lacking some important fine detail (like failing to mention that Security Modes appear in ‘PascalCase’, rather than ‘camelCase’ as they are in the capability and as is the usual ST convention), the Rules API Reference does at least suggest how to use the Security Mode in a condition. It makes no mention of the setting the Security Modes in an action. By contrast the Core SDK seems to be interested in ‘armState’ which doesn’t appear in the Reference, but omits much of the other location stuff that is there.

There are no mentions of sending notifications at all.

However if the Automations have been migrated to the Rules API, surely that means both are actually supported?

The Rules API is moving into the prime time now, so it would help greatly if there was consistency over how it is documented.

The same really applies across the board. I can pull notifications and device history out of the API should I want to and yet there isn’t a sniff of them in the Reference. I am not expecting direct access to the API (Postman, curl etc), the SDK and CLI to be in perfect harmony as the CLI depends on the SDK which depends on the API. There is a natural order there though. The API Reference needs to document anything that is live, proposed, deprecated or dead in the API, as is done for capabilities. Those should equate to ‘works unless something has broken’, ‘your mileage may vary’, ‘lingering like a bad smell’, and ‘too late’. Once you have that sorted the rest should be able to follow naturally.

I also noted the old SDC.webcore.co proof of concept claimed to handle ‘changes’ type conditions. I didn’t test that live but rather assumed that isn’t really the case as anything that major and that old would have to be mentioned somewhere.

[/quote]

APIs are designed to be consumed, it is important to make sure that the client, or consumer, is able to quickly implement an API and understand what is happening with it. Unfortunately, many APIs make implementation extremely difficult, defeating their very purpose. As you build out your API you want to ensure that you not only provide informational API documentation to help your developers integrate/ debug connections, but also return back relevant data whenever a user makes a call especially a call that fails.

4

Documentation? What documentation. Half the stuff we discuss on this forum every day is still undocumented. The documentation has never been adequate.