cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Chiradeep Vittal <Chiradeep.Vit...@citrix.com>
Subject Re: [Discuss] API name alias
Date Tue, 09 Apr 2013 18:04:59 GMT
In Kishan's case he is adding a better, accurate name for the API. The API
was misnamed in the previous version (ACL = Access Control List, but ACL
was referring to an individual item within the list). Similarly, there are
other poorly worded APIs (createIpForwardingRule instead of
createStaticNat comes to mind).

On 4/9/13 2:19 AM, "Rohit Yadav" <bhaisaab@apache.org> wrote:

>On Tue, Apr 9, 2013 at 12:04 PM, Chiradeep Vittal <
>Chiradeep.Vittal@citrix.com> wrote:
>
>> 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.
>>
>
>Chiradeep, if there are multiple apinames for the same operation (cmd
>class) where does the question of "correct alias to use" come?
>
>Excuse my ignorance, I don't understand why we need "preferred" and
>"deprecated" fields in that respect. IMO it won't solve any problem but
>add
>confusion and ambiguity, unless there is some use you may explain?
>
>As Kishan shares, he would use the array styled approach which John
>suggested and I think it should work, why we want preferred and deprecated
>Strings or String[].
>
>Cheers.
>
>
>> On 4/8/13 9:52 PM, "Rohit Yadav" <bhaisaab@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.Vittal@citrix.com> wrote:
>> >
>> >>
>> >>
>> >> On 4/8/13 11:18 AM, "Rohit Yadav" <bhaisaab@apache.org> wrote:
>> >>
>> >> >On Mon, Apr 8, 2013 at 7:10 PM, John Burwell <jburwell@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"})
>> >> >>
>> >> >> 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 <bhaisaab@apache.org>
>>wrote:
>> >> >>
>> >> >> > On Mon, Apr 8, 2013 at 6:33 PM, Kishan Kavala
>> >> >><Kishan.Kavala@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')
>> >>
>> >>
>>
>>


Mime
View raw message