Deprecating functions and params in the MOBILE_API

[justinjdickow]

We should consider defining a way of deprecating the functions and parameters in MOBILE_API such that answers to questions like Mike's regarding the use of different parameter keys for OnSystemRequest are obvious. (If the V1 url and timeout parameter keys are still valid in the current version, they would be shown as deprecated, otherwise they would be removed)

[justinjdickow]

After some internal discussion today

• This issue should be moved to a new repository specifically for versioning the RPC specification
• In order to properly maintain the RPC specification we should introduce three new fields.
  1. A Deprecation field to parameters and functions in the xml which denotes the version of the specification that the function or parameter was deprecated
  2. An Introduced which denotes the version of the specification that the function or parameter was introduced
  3. A Replaces field for if the new function or parameter replaces an existing one in new versions.

The following are two examples which enable better versioning using the above proposal.

Example 1

In previous versions of the MOBILE_API.xml specification the OnSystemRequest notification had a parameter called "URL", which at some point was changed to "url". Now, the mobile proxies have to support both fields, and make an assumption (because it is not officially documented) about the versions in which the parameter key was "URL". According to the above proposal the following would be valid and identify when the parameter was replaced, what it was replaced by, and what versions are supported.

<param name="URL" type="String" maxlength="1000" minsize="1" maxsize"100" array="true" mandatory="false" deprecated="2.0"></param>
<param name="url" type="String" maxlength="1000" minsize="1" maxsize="100" array="true" mandatory="false" replaces="URL" introduced="2.0"></param>

Example 2

If the key is not changed, but a field such as maxlength is changed, the parameter is deprecated, a new parameter is introduced with the same name, and the assumption is that it replaces the deprecated parameter. In this case, the replaces field is redundant and can be excluded.

<param name="url" type="String" maxlength="1000" minsize="1" maxsize"100" array="true" mandatory="false" deprecated="2.0"></param>
<param name="url" type="String" maxlength="256" minsize="1" maxsize="100" array="true" mandatory="false" introduced="2.0"></param>

[Jack-Byrne]

Mobile API revisions was covered by this sdl evolution proposal https://github.com/smartdevicelink/sdl_evolution/blob/e139f7a04511d4b933c54a77fab3c1b2d4289ee7/proposals/0089-mobile-api-versioning.md