Thanks everyone for your inputs. We should avoid making changes to the APIs which have only one name. So they'll continue to have the annotation:
@APICommand(name="apiName1") For APIs with multiple names, we should support String[] as suggested by John. Preferred and deprecated would be required in case of multiple API names. Preferred and deprecated params should also support String[]. @APICommand(name={'Foo', 'Bar', 'FooBar'}, preferred='Foo', deprecated={'Bar','FooBar'}) > -----Original Message----- > From: Chiradeep Vittal [mailto:chiradeep.vit...@citrix.com] > Sent: Tuesday, 9 April 2013 12:05 PM > To: dev@cloudstack.apache.org > Subject: Re: [Discuss] API name alias > > Rohit, that's like saying we won't fix a leaky faucet today because we're > moving in a couple of years anyway. It isn't a big deal to add this and it > clarifies to the end user what is the correct alias to use. > > On 4/8/13 9:52 PM, "Rohit Yadav" <bhais...@apache.org> wrote: > > >If we are still on our previously discussed plan (search a wiki shared > >by > >Min) on deprecating the whole query based API (Server), it's just > >unnecessary work on present APIs. I think for now just changing the > >name attribute type from String to String[] would just work, as John > suggested. > > > >Adding other fields, may not hold much use for now. Except for few of > >them the rest of 300 apis will have preferred == current apiname and > >deprecated as blank string. > > > >I think we should just deprecated all cmd classes (query based) over a > >long period say 1 or 2 years, and/or find a way to rewrite/refactor > >them so as to reuse them with our new rest based API server for future. > > > >Cheers. > > > >On Tue, Apr 9, 2013 at 3:18 AM, Chiradeep Vittal < > >chiradeep.vit...@citrix.com> wrote: > > > >> > >> > >> On 4/8/13 11:18 AM, "Rohit Yadav" <bhais...@apache.org> wrote: > >> > >> >On Mon, Apr 8, 2013 at 7:10 PM, John Burwell <jburw...@basho.com> > >>wrote: > >> > > >> >> Rohit, > >> >> > >> >> Why would we need to rewrite any Java code to switch to an array? > >>As I > >> >> mentioned, array annotation values are treated as varargs. > >>Therefore, > >> >> annotations with single values can be left alone. Only cases > >> >> where multiple values are required would require the addition of > >> >> curly > >>braces. > >> >> For example, for an APICommand with one name, the following would > >> >>continue to work: > >> >> > >> > > >> >Hey John, you're right but it's a matter of code styling, I prefer > >> >writing; > >> > > >> >@APICommand(name = {'name1'}) even if it's only one name, this way > >> >any subsequent api author would know that name is an array and they > >> >can > >>have > >> >aliases which is what Kishan wants. > >> > > >> > > >> >> > >> >> @APICommand(name="apiName1") > >> >> > >> >> While for an APICommand with multiple names, the following form > >> >>would now be supported: > >> >> > >> >> @APICommand(name={"apiName1", "apiName2", > >> >> "apiName3"})@APICommand(name={"apiName1", "apiName2", > >> >> "apiName3"})@APICommand(name={"apiName1", "apiName2", "apiName3"}) > >> >> > >> >> I am not familiar with the Marvin code, so I can not speak to the > >>impact > >> >> of this change to it. However, the only changes to the Java code > >> >>should be the API commands with multiple names and the classes > >> >>that actually consume the value of this annotation. > >> >> > >> > > >> >Yes, you're right we can skip the code styling I referred then it > >> >won't consume much coding, we just need to fix these; > >> > > >> >- Fix APICommand annotation interface definition to accept name as > >> >an array > >> >- Fix method in ApiServer which creates apiname->cmdclass map to > >> >care > >>for > >> >aliases > >> >- Fix ApiDiscovery to take care of the aliases (create different > >>response > >> >objs for the same cmd class) > >> >- Fix apidocs XmlWriter class to take of the aliases and the api > >> >html generator to process the same. > >> >- Fix Marvin's codegenerator.py to take care of the aliases (which > >>means > >> >create apiname related modules which would contain cmd and response > >> >boilterplate fields/class) > >> > > >> >Cheers. > >> > > >> > > >> >> > >> >> Thanks, > >> >> -John > >> >> > >> >> On Apr 8, 2013, at 9:22 AM, Rohit Yadav <bhais...@apache.org> wrote: > >> >> > >> >> > On Mon, Apr 8, 2013 at 6:33 PM, Kishan Kavala > >> >><kishan.kav...@citrix.com > >> >> >wrote: > >> >> > > >> >> >> APICommand annotation in API Cmd object has a name parameter. > >> >>Currently > >> >> >> name parameter takes only one value. I plan to enhance this to > >> >>support > >> >> >> comma separated values. This will allow multiple API names for > >> >> >> the > >> >>same > >> >> API > >> >> >> Cmd object. > >> >> >> > >> >> >> Current: > >> >> >> @APICommand(name = "apiName1", .. > >> >> >> > >> >> >> Proposed: > >> >> >> @APICommand(name = "apiName1, apiAlias2, apiAlias3", .. > >> >> >> > >> >> > > >> >> > It's a hack, but doable. While not elegant as John suggests, > >>parsing > >> >> comma > >> >> > separated value can lead to some issues. > >> >> > > >> >> > Changing the name field to array would require a lot of > >> >> > rewriting > >>the > >> >> > present apis annotation name fields, again doable by a small > >> >> > python > >> >> program > >> >> > (like the one I used in the last name field refactoring). > >> >> > > >> >> > This would really help remove duplicate cmd classes for apis > >> >> > such > >>as > >> >>copy > >> >> > iso and volume which does the same job but requires two > >> >> > different > >>cmd > >> >> class > >> >> > implementations. > >> >> > > >> >> > Whatever way you decide, pl. make sure to fix ApiDiscovery, > >>ApiServer > >> >> > cmdclass-apiname map generator method and apidocs generation > >> >>accordingly. > >> >> > > >> >> > Cheers. > >> >> > > >> >> > > >> >> >> > >> >> >> Requirement: > >> >> >> As part of CLOUDSTACK-763, I'll be introducing NetworkACLList > >> >>(grouping > >> >> of > >> >> >> NetworkACLItems). Current APIs use *NetworkACL (create > >> >> >> NetworkACL/deleteNetworkACL etc..) for NetworkACLItem related > >>APIs. > >> >> These > >> >> >> APIs have to be changed to *NetworkACL Item(create > >> >> >> NetworkACLItem/deleteNetworkACLItem etc..) to get the > >> >> >> terminology > >> >> right. We > >> >> >> also need to support old API names for backward compatibility. > >>Hence > >> >>the > >> >> >> need for API name alias. > >> >> >> > >> >> >> Terminology: > >> >> >> NetworkACLItem - Individual ACL Entry (was NetworlACL earlier). > >> >> >> NetworkACL - Group of Network ACL Items. API will use the term > >> >> >> NetworkACLList to differentiate from the existing NetworkACL APIs. > >> >> >> > >> > >> How about an additional attribute 'preferred' or 'deprecated' ? > >> > >> @APICommand(name={'Foo', 'Bar'}, preferred='Foo', deprecated='Bar') > >> > >>