[DISCUSS] API versioning
Hi I recently developed ansible modules for the ACL API and ... found this has a really inconsistent API naming. E.g. createNetworkACL <<-- this creates an ACL rule createNetworkACLList <<-- this create the ACL updateNetworkACLItem <<-- this updates an ACL rule updateNetworkACLList <<-- this updates the ACL My first thoughs was, someone has to fix this, like createNetworkAclRule <<-- this create the ACL rule createNetworkAcl <<-- this creates an ACL updateNetworkAclRule <<-- this updates the ACL rule updateNetworkAcl <<-- this updates an ACL But how without breaking the API for backwards compatibility? I know a few other places where the API has inconsistent namings. Fixing the API but in a controlled way? What about by adding a version to the API? I would like to introduce a API versioning to cloudstack: The current API would be frozen into verison v1. The new API will have v2. The versioned API has the URL scheme: /client/api/ The current API would be /client/api/v1 and the /client/api would be an alias for v1. This ensures backwards compatibility. This would allow us to deprecate and change APIs. Any thoughts?
Re: [DISCUSS] API versioning
+1. I like it. On Jun 4, 2017 5:04 AM, "Rene Moser" wrote: > Hi > > I recently developed ansible modules for the ACL API and ... found this > has a really inconsistent API naming. E.g. > > createNetworkACL <<-- this creates an ACL rule > createNetworkACLList <<-- this create the ACL > > updateNetworkACLItem <<-- this updates an ACL rule > updateNetworkACLList <<-- this updates the ACL > > My first thoughs was, someone has to fix this, like > > createNetworkAclRule <<-- this create the ACL rule > createNetworkAcl <<-- this creates an ACL > > updateNetworkAclRule <<-- this updates the ACL rule > updateNetworkAcl <<-- this updates an ACL > > But how without breaking the API for backwards compatibility? I know a > few other places where the API has inconsistent namings. Fixing the API > but in a controlled way? What about by adding a version to the API? > > I would like to introduce a API versioning to cloudstack: The current > API would be frozen into verison v1. The new API will have v2. The > versioned API has the URL scheme: > > /client/api/ > > The current API would be /client/api/v1 and the /client/api would be an > alias for v1. This ensures backwards compatibility. > > This would allow us to deprecate and change APIs. > > Any thoughts? > > > >
Re: [DISCUSS] API versioning
This sounds like a good idea to me. > On Jun 4, 2017, at 8:24 AM, Will Stevens wrote: > > +1. I like it. > >> On Jun 4, 2017 5:04 AM, "Rene Moser" wrote: >> >> Hi >> >> I recently developed ansible modules for the ACL API and ... found this >> has a really inconsistent API naming. E.g. >> >> createNetworkACL <<-- this creates an ACL rule >> createNetworkACLList <<-- this create the ACL >> >> updateNetworkACLItem <<-- this updates an ACL rule >> updateNetworkACLList <<-- this updates the ACL >> >> My first thoughs was, someone has to fix this, like >> >> createNetworkAclRule <<-- this create the ACL rule >> createNetworkAcl <<-- this creates an ACL >> >> updateNetworkAclRule <<-- this updates the ACL rule >> updateNetworkAcl <<-- this updates an ACL >> >> But how without breaking the API for backwards compatibility? I know a >> few other places where the API has inconsistent namings. Fixing the API >> but in a controlled way? What about by adding a version to the API? >> >> I would like to introduce a API versioning to cloudstack: The current >> API would be frozen into verison v1. The new API will have v2. The >> versioned API has the URL scheme: >> >> /client/api/ >> >> The current API would be /client/api/v1 and the /client/api would be an >> alias for v1. This ensures backwards compatibility. >> >> This would allow us to deprecate and change APIs. >> >> Any thoughts? >> >> >> >>
