It might be a total pipe dream, but if the API was also Swagger compliant, it would simplify our API documentation and would make API tooling much easier. I have not looked into what would be required, but it would definitely be a nice to have. :)
*Will STEVENS* Lead Developer *CloudOps* *| *Cloud Solutions Experts 420 rue Guy *|* Montreal *|* Quebec *|* H3J 1S6 w cloudops.com *|* tw @CloudOps_ On Fri, May 20, 2016 at 11:12 AM, Rafael Weingärtner < rafaelweingart...@gmail.com> wrote: > Hi guys, > I agree with Daan that if class fields have improper (not descriptive or > not suitable) names we should change them. However, I do not find the > change (on variable names) introduced by PR #816 good. It added an > “_”(underline) before variable names; even though Apache CloudStack has a > lot of that currently, I think that is a pattern we should avoid. > > Your ideas to use annotations to avoid relying on variable names are great; > but, let’s not re-create the well here. There is a research [1] that has > been conducted in 2014 that tackled exactly that problem; the proposal > presented in [1] decoupled client and server sides from variable name by > using semantic annotations. The concept, the formalization and the > experiments are all presented in paper [1]. The serialization and > deserialization core of the proposal presented in [1] can be found in [2]. > > The idea of decoupling our web APIs from variable names is great, but it is > something that will require some effort to be fully and properly > implemented. If you wish to push that forward count on me. > > [1] http://ieeexplore.ieee.org/xpls/abs_all.jsp?arnumber=6928953&tag=1 > [2] https://github.com/ivansalvadori/gsonld > > > On Fri, May 20, 2016 at 3:30 AM, Daan Hoogland <daan.hoogl...@gmail.com> > wrote: > > > Guys, we should rename fields that have improper names. I do not agreee > > with the statement at all. Your two solutions to the serialisation hazard > > are both acceptable to me. leaving a non compliant or non explanatory > name > > in because it slipped through the nets at some points does not seem > > acceptable to me. We must improve are code. > > > > On Fri, May 20, 2016 at 6:53 AM, Tutkowski, Mike < > > mike.tutkow...@netapp.com> > > wrote: > > > > > Thanks for sending out this e-mail, Anshul. > > > > > > This is a bit of a strange situation because we need to make sure > people > > > are either aware of the fact that properties in Command classes are > > > serialized (and not change existing variable names) or come up with a > > less > > > fragile way of choosing property names when sending data (perhaps using > > > annotations). > > > > > > At the very least, we should have comments in these classes indicating > > the > > > dangers of changing property names. It might also be beneficial to have > > > unit tests in place that expect certain variable names and assert if > they > > > are not as expected. > > > > > > In the meanwhile, I plan to change the variable names back that were > > > changed in PR #816. > > > > > > Additional thoughts on how this should be addressed long term? > > > > > > Thanks! > > > Mike > > > ________________________________________ > > > From: Anshul Gangwar <anshul.gang...@accelerite.com> > > > Sent: Thursday, May 19, 2016 10:47 PM > > > To: dev@cloudstack.apache.org > > > Subject: Variable renaming in classes meant for Agents > > > > > > Hi, > > > > > > We should not allow renaming of variables in classes which ends with > > > Command and TO. As these objects are meant to be consumed by Agents. > > > > > > Agents may not be written in java so relying on these variable names to > > > get the info. One such example is Hyper-V agent. > > > > > > Hyper-V support is currently broken as there are some variables renamed > > in > > > PR https://github.com/apache/cloudstack/pull/816. > > > > > > Regards, > > > Anshul > > > > > > > > > > > > > > > > > > > > > DISCLAIMER > > > ========== > > > This e-mail may contain privileged and confidential information which > is > > > the property of Accelerite, a Persistent Systems business. It is > intended > > > only for the use of the individual or entity to which it is addressed. > If > > > you are not the intended recipient, you are not authorized to read, > > retain, > > > copy, print, distribute or use this message. If you have received this > > > communication in error, please notify the sender and delete all copies > of > > > this message. Accelerite, a Persistent Systems business does not accept > > any > > > liability for virus infected mails. > > > > > > > > > > > -- > > Daan > > > > > > -- > Rafael Weingärtner >
