You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by Prasanna Santhanam <ts...@apache.org> on 2013/04/16 10:01:15 UTC
API naming conventions
Is there a formal document somewhere describing the naming conventions
for our APIs? If not is it worthwhile starting one?
The document should describe:
1. valid action (verbs) to operate on an entity
2. entity being the desired resource, physical device, cloudstack
account etc.
3. what semantics an update API can take and what a configure API can
take etc.
Thanks,
--
Prasanna.,
Re: API naming conventions
Posted by Prasanna Santhanam <ts...@apache.org>.
On Tue, Apr 16, 2013 at 06:02:43PM +0530, Rohit Yadav wrote:
> Use what we have been using so far:
>
> API := <lowercase action>:<CamelCaseSubjects>
>
> lowecase action := <add| remove | list | etc....>
> CamelCaseSubjects := <Users|Zones|VirtualMachines|...|*subjects*...>
>
> So, based on such rule; the following makes sense:
> - configLdap
>
> About subjects, think what the API is trying to do. For example;
>
> addToLoadBalancerRule does not make sense, what are we adding to
> LoadBalancerRule, probably a rule right? So, in that
> case addLoadBalancerRule makes sense.
>
Indeed, the grammar is something few people are aware of. Reason why
we have APIs that don't conform to it. So it's better to codify this
in a wiki.
I'm still looking to understand when we create a new API vs
overloading an existing API. Sometimes this depends on the breakdown
of operations. For instance, the LoadBalancerRule API only creates the
LB Rule while adding instances to that rule is a different operation.
So two APIs were created for the purpose.
--
Prasanna.,
Re: API naming conventions
Posted by Rohit Yadav <bh...@apache.org>.
Use what we have been using so far:
API := <lowercase action>:<CamelCaseSubjects>
lowecase action := <add| remove | list | etc....>
CamelCaseSubjects := <Users|Zones|VirtualMachines|...|*subjects*...>
So, based on such rule; the following makes sense:
- configLdap
About subjects, think what the API is trying to do. For example;
addToLoadBalancerRule does not make sense, what are we adding to
LoadBalancerRule, probably a rule right? So, in that
case addLoadBalancerRule makes sense.
Cheers.
On Tue, Apr 16, 2013 at 4:33 PM, Prasanna Santhanam <ts...@apache.org> wrote:
> Oh that's more than I intend to chew :)
>
> I only want the APIs to have some defined pattern - naming and
> semantics. This if from a integration perspective than from the
> perspective of a developer of cloudstack.
>
> There is currently no documentation on what I should name my API and
> how I choose b/w overloading an API vs creating a new API:
>
> 1. ldapConfig or configLdap?
> 2. addToLoadBalancerRule/removeFromLoadBalancerRule or simply
> addLoadBalancerRule and removeLoadBalancerRule with overloaded
> arguments for specifying the rule itself.
>
> --
> Prasanna.,
>
> On Tue, Apr 16, 2013 at 10:40:44AM +0000, Nitin Mehta wrote:
> > +1 to this, but I guess this should be a subsection of a wiki called
> > "Adding a new api in Cloudstack - What all should I do ?"
> >
> > Some of the subsections in it should be like (each with an example) :-
> >
> > API naming conventions
> > Should the api be sync, async or asynccreate and what class should it
> > extend
> >
> > API annotations and what they mean. Discuss ACL and parameters. Events to
> > write.
> > What to put in the API layer, manager layer, hypervisor layer
> > API Response - should I create a view (in case its a list command)
> > Testing expectations - Adding marvin tests
> >
> > I guess this would be very useful to the devs, guys trying to understand
> > the flow. So lets create one consolidated wiki and add these subsections.
> >
> > Thanks,
> > -Nitin
> >
> > On 16/04/13 1:31 PM, "Prasanna Santhanam" <ts...@apache.org> wrote:
> >
> > >Is there a formal document somewhere describing the naming conventions
> > >for our APIs? If not is it worthwhile starting one?
> > >
> > >The document should describe:
> > >1. valid action (verbs) to operate on an entity
> > >2. entity being the desired resource, physical device, cloudstack
> > >account etc.
> > >3. what semantics an update API can take and what a configure API can
> > >take etc.
> > >
> > >Thanks,
> > >
> > >--
> > >Prasanna.,
>
>
RE: API naming conventions
Posted by Koushik Das <ko...@citrix.com>.
A fixed naming pattern with verb followed by noun looks good. If required the verbs can be categorized further like lifecycle verbs - create, delete etc.
> -----Original Message-----
> From: prasanna [mailto:srivatsav.prasanna@gmail.com] On Behalf Of
> Prasanna Santhanam
> Sent: Tuesday, April 16, 2013 4:34 PM
> To: dev@cloudstack.apache.org
> Subject: Re: API naming conventions
>
> Oh that's more than I intend to chew :)
>
> I only want the APIs to have some defined pattern - naming and semantics.
> This if from a integration perspective than from the perspective of a
> developer of cloudstack.
>
> There is currently no documentation on what I should name my API and how
> I choose b/w overloading an API vs creating a new API:
>
> 1. ldapConfig or configLdap?
> 2. addToLoadBalancerRule/removeFromLoadBalancerRule or simply
> addLoadBalancerRule and removeLoadBalancerRule with overloaded
> arguments for specifying the rule itself.
>
> --
> Prasanna.,
>
> On Tue, Apr 16, 2013 at 10:40:44AM +0000, Nitin Mehta wrote:
> > +1 to this, but I guess this should be a subsection of a wiki called
> > "Adding a new api in Cloudstack - What all should I do ?"
> >
> > Some of the subsections in it should be like (each with an example) :-
> >
> > API naming conventions
> > Should the api be sync, async or asynccreate and what class should it
> > extend
> >
> > API annotations and what they mean. Discuss ACL and parameters. Events
> > to write.
> > What to put in the API layer, manager layer, hypervisor layer API
> > Response - should I create a view (in case its a list command) Testing
> > expectations - Adding marvin tests
> >
> > I guess this would be very useful to the devs, guys trying to
> > understand the flow. So lets create one consolidated wiki and add these
> subsections.
> >
> > Thanks,
> > -Nitin
> >
> > On 16/04/13 1:31 PM, "Prasanna Santhanam" <ts...@apache.org> wrote:
> >
> > >Is there a formal document somewhere describing the naming
> > >conventions for our APIs? If not is it worthwhile starting one?
> > >
> > >The document should describe:
> > >1. valid action (verbs) to operate on an entity 2. entity being the
> > >desired resource, physical device, cloudstack account etc.
> > >3. what semantics an update API can take and what a configure API can
> > >take etc.
> > >
> > >Thanks,
> > >
> > >--
> > >Prasanna.,
Re: API naming conventions
Posted by Prasanna Santhanam <ts...@apache.org>.
Oh that's more than I intend to chew :)
I only want the APIs to have some defined pattern - naming and
semantics. This if from a integration perspective than from the
perspective of a developer of cloudstack.
There is currently no documentation on what I should name my API and
how I choose b/w overloading an API vs creating a new API:
1. ldapConfig or configLdap?
2. addToLoadBalancerRule/removeFromLoadBalancerRule or simply
addLoadBalancerRule and removeLoadBalancerRule with overloaded
arguments for specifying the rule itself.
--
Prasanna.,
On Tue, Apr 16, 2013 at 10:40:44AM +0000, Nitin Mehta wrote:
> +1 to this, but I guess this should be a subsection of a wiki called
> "Adding a new api in Cloudstack - What all should I do ?"
>
> Some of the subsections in it should be like (each with an example) :-
>
> API naming conventions
> Should the api be sync, async or asynccreate and what class should it
> extend
>
> API annotations and what they mean. Discuss ACL and parameters. Events to
> write.
> What to put in the API layer, manager layer, hypervisor layer
> API Response - should I create a view (in case its a list command)
> Testing expectations - Adding marvin tests
>
> I guess this would be very useful to the devs, guys trying to understand
> the flow. So lets create one consolidated wiki and add these subsections.
>
> Thanks,
> -Nitin
>
> On 16/04/13 1:31 PM, "Prasanna Santhanam" <ts...@apache.org> wrote:
>
> >Is there a formal document somewhere describing the naming conventions
> >for our APIs? If not is it worthwhile starting one?
> >
> >The document should describe:
> >1. valid action (verbs) to operate on an entity
> >2. entity being the desired resource, physical device, cloudstack
> >account etc.
> >3. what semantics an update API can take and what a configure API can
> >take etc.
> >
> >Thanks,
> >
> >--
> >Prasanna.,
Re: API naming conventions
Posted by Nitin Mehta <Ni...@citrix.com>.
+1 to this, but I guess this should be a subsection of a wiki called
"Adding a new api in Cloudstack - What all should I do ?"
Some of the subsections in it should be like (each with an example) :-
API naming conventions
Should the api be sync, async or asynccreate and what class should it
extend
API annotations and what they mean. Discuss ACL and parameters. Events to
write.
What to put in the API layer, manager layer, hypervisor layer
API Response - should I create a view (in case its a list command)
Testing expectations - Adding marvin tests
I guess this would be very useful to the devs, guys trying to understand
the flow. So lets create one consolidated wiki and add these subsections.
Thanks,
-Nitin
On 16/04/13 1:31 PM, "Prasanna Santhanam" <ts...@apache.org> wrote:
>Is there a formal document somewhere describing the naming conventions
>for our APIs? If not is it worthwhile starting one?
>
>The document should describe:
>1. valid action (verbs) to operate on an entity
>2. entity being the desired resource, physical device, cloudstack
>account etc.
>3. what semantics an update API can take and what a configure API can
>take etc.
>
>Thanks,
>
>--
>Prasanna.,