API separators, "=" vs " "

Doug - K3TZR · July 2017

Some API commands are in the form <name=value> whereas other are <name value>. I believe individual commands require one form or the other. In future versions could the API be made to accept either separator? That wouldn't break old code but would make the API more consistent.

John G3WGV · July 2017

This seems like a reasonable suggestion.

There are similar protocol variations in the command responses which makes parsing more complex. There's probably a perfectly good reason for these differences and I'm not suggesting that any changes need to be made, especially if to do so would damage backward compatibility. Is there an API design document that discusses these differences and the rationale?

Steve-N5AC · July 2017

In general, commands that need parameters have parameters in a "command parameter parameter..." structure. If the parameters to commands are name/value pairs, then the name/value pairs are separated with = and the parameters are separated with space. For example:

radio filter_sharpness DIGITAL level=3 auto_level=0

Does this help understand why it's this way? If this doesn't "cover it," please provide some examples we can look at and think about.

Just as a side note, my original goal was to use a recursive descent parser for the API and I was amazed that the tools to do this in C were awful. I made several aborted attempts at it while the API was growing and finally gave up on the idea (too much to do, so little time). As a result, the API is parsed with CRT primitives (strnlen, strncmp, etc). Altering an API that does not have a grammar codified is considerably harder. The method we ended up with is also responsible for any inconsistencies you see. Having said this, we have altered some commands for required updates and made it so they would work with either a past or new format (slice is an example). With so many programs using the API at this point, we would have to look carefully at any changes, especially sweeping ones.

John G3WGV · July 2017

Great reply, thanks Steve.

I don't think this is worth spending time on - we've gotten used to the API's little quirks and it isn't really that hard to parse, honest! I'd far rather any effort on the API was put into adding functionality, for example, the persistent client identifier suggestion that I discussed with Ed when I visited back in May.

Doug - K3TZR · July 2017

Thanks to everyone for their comments.

Here's a simple example:

interlock tx1_delay=<value>

vs

cw break_in_delay <value>

Both are in the form <command> <param> <value> but one use "=" and the other uses " " to separate the <param> from the <value>.

Small difference but it makes the code to format commands dependent on specific knowledge of each command rather than knowledge of the pattern followed by all commands.

Steve-N5AC · July 2017

Yep, totally agree that this is inconsistent. I've entered an issue (#5040) in our tracker to look into changing this. Thanks!

Doug - K3TZR · July 2017

Thanks Steve

API separators, "=" vs " "

Comments

Leave a Comment

Categories