Proposal API help

Introduction

Abstract

The API protocol, unlike the command line (and by extension - the Telnet and SSH protocols), does not offfer a way for RouterOS to report to the client the available commands, menus, attributes or attribute values. This proposal suggests a new API protocol specific command called "/help" that behaves similarly to a "?" in the command line, in that it will fill this gap, and it should hopefully be relatively easy to implement by MikroTik due to its similarity with the "?" help.

Terminology

• API protocol - The syntax defined in the corresponding manual page.
• API client - A general purpose implementation of the API protocol for use in a programming language. All "Examples" at the end of the above manual page are essentially API clients.
• (API) application - A program or script written in a programming language that uses an API client as part of its functionality.
• Users - People using API clients inside their applications or otherwise interact directly with the API protocol.
• End users - People for which the "Users" write the API applications.

Use cases

"Why would such a feature even be needed in a protocol intended for machine consumption?" you may ask. There are several notable use cases:

• Utility methods in API clients may sometimes need to behave differently based on the presence or absence of a command at a particular menu. Case in point: The "move" command, based on which API clients respectively may support or should avoid supporting "numbers" emulation at the given menu.
• API clients will be able to (if the user wants to) pre-validate commands (or at least some of the more trivial aspects of command calls), lessening the load on the router at the expense of the API application.
• Applications could be written that generate classes (or the equivalent in whatever language the API protocol is used from) representing each menu/command, allowing IDEs to seamlessly assist users when creating API applications.
• Because most commands are shared between scripting and API, one could also make an application that uses this command to generate auto-complete suggestions for ".rsc" files.
• It lets applications potentially detect upgrades to RouterOS, and in turn verify automatically that there are no breaking changes as a result. Case in point: v5's "target-address"/"interface" combo in "/queue simple" vs. v6's "target".

Syntax

No arguments

When the "/help" command is called with no arguments, only a single "!done" reply should be given, with a "ret" attribute that has a hash value in it. The hash should be computed based on the names and build times of all installed and enabled RouterOS packages.

The actual hash algorithm may be changed, without any prior notice, from one RouterOS build to the next. The only thing that applications should be able to safely assume about it is that it would be different whenever RouterOS is upgraded/downgraded, or if a RouterOS package is installed/uninstalled/upgraded/downgraded/enabled/disabled.

Note: MD5 or SHA1 are good choices here, since collisions are not easy enough to create when the whole data is a small series of names and times, and there's no security concern here.

Note: Version numbers are intentionally avoided, as to allow seamless uses of improperly labeled RC versions of RouterOS or its packages.

Warning: Applications MUST NOT assume ANY particular hashing algorithm or alphabet of the hash. When storing the hash, applications should take care to escape the value for whatever context they are storing it in.

Example:

/help

!done

=ret=ebddd18303a54111e2dea05a92ab46b4

The purpose of this hash is to allow applications to "cache" the other results from "/help", particularly in cases where an application is examining the whole of RouterOS. For example, an object generator may generate different sets of objects for different RouterOS hostnames, but not bother regenerating them when there's no need to.

Enabling/Disabling a package affects the given hash, because enabling/disabling a package will more often than not affect the presence of menus, commands, attributes and attribute values, which is the primary use case for making an overall examination of RouterOS to begin with.