Summary:ASTERISK-06085: [discussion] Need a way to deprecate manager APIs
Reporter:Tilghman Lesher (tilghman)Labels:
Date Opened:2006-01-14 23:04:08.000-0600Date Closed:2011-06-07 14:11:57
Versions:Frequency of
Description:I'm looking at deprecating the manager commands DBPut and DBGet, in favor of using Setvar and Getvar to the related dialplan function.

The problem is that manager API is meant to be automated, so a human is unlikely to see any responses (meaning persons writing to the manager API are unlikely to see a deprecation warning and won't know an API has been deprecated until it is removed -- and something stops working).

My suggestion, to be debated and/or modified by the other developers, would be a twofold attack:
1.  We notate for the upcoming version that these commands are deprecated for 1.4 and will be removed in 1.6.  We notate this in UPGRADE.txt.
2.  We add an API mandate that API writers pay special attention to any manager response that includes a "Warning:" header, logging the message for later consideration and/or presenting the contents to the user.  In this way, we will be able to quickly warn of future deprecation in the manager API.
Comments:By: Matt O'Gorman (mogorman) 2006-01-15 00:01:58.000-0600

I think the best way to deal with the manager api, is to use the tools we already have in place.  The manager version number.  I think asterisk 1.4 should support manager 1.0 and manager x, where x is the newer version without depricated apis.  when 1.6 rolls around we drop 1.0 compatibility, and we depricate x for manager y and so on.

By: Stefan Reuter (srt) 2006-01-18 19:34:52.000-0600

I am currently using "show files version" in Asterisk-Java to behave different depending on the version of different modules. Using the manager version might work but I doubt it would be very helpful for the real world. First there are some patches out there that change the version (for example bristuffed Asterisk 1.2 uses 1.2 where vanilla Asterisk 1.2 still uses 1.0). Second this doesnt help people running trunk.
I dont think a warning property would help as there is nothing an end user can really do with it.
What would help is a better documentation (in the sense of an API reference)  and delta documentation for each release plus an "official" way to determine the base version of Asterisk and any applied patches.

By: Olle Johansson (oej) 2006-01-20 14:55:09.000-0600

I do think we have to start using the manager version number and document changes in a managerversion.readme file for developers.