I suppose that in openAPI, one would have to identify {/diskofferingid,
zoneid//and ///snapshotid/} /as parameters and use the parameter
description to explain when each parameter is used.
Rough outline
swagger: '2.0'
info:
version: 5.0.0
title: Volume Management Service
description: Manage volumes
schemes:
- https
host: cloudstack.apache.org
basePath: /manager
paths:
/createVolume:
post:
summary: Creates a volume
description: Creates a volume based on ... or from a snapshot
parameters:
- name: diskofferingid
in: query
description: Offering id. Required with zoneid when .....
type: integer
- name: zoneid
in: query
description: Zone id. Required with diskofferingid when
creating...
type: integer
- name: snapshotid
in: query
description: Snapshot id. Used when creating a volume from a
snapshot..
type: integer
responses:
200:
description: Volume created successfully
401:
description: Not authorized. User unknown.
403:
description: Insufficient privileges.
406:
description: Parameters failed validation.
408:
description: Request timeout
500:
description: Internal server Error
This would seem to be more or less analogous to what the code actually
does.
It accepts any set of parameters initially and from the context, decides
which ones are required and which ones are optional and which ones are
not acceptable.
Perhaps not a perfect solution but certainly goes a long way to getting
a consistent and somewhat rigorous definition of the API.
Depending on the quality and completeness of the descriptions, someone
reading the openAPI reports would have a pretty good idea about how to
use the createVolume service.
Ron
On 06/06/2017 11:44 AM, Syed Ahmed wrote:
The interesting thing about Cloudstack's API is that not all
parameters are required and based on what is being used, a set of
parameters is required. For example: take the createVolume API.
If you are creating a new volume, the required args are:
{/diskofferingid, zoneid//} /and if you use a snapshot to create the
volume, the required args are {/snapshotid/}//This kind of dependency
is very hard to represent in Swagger. I haven't found any tool that
correctly represents the relation between different args as yet. Do
you guys have any idea?
On Mon, Jun 5, 2017 at 2:23 PM, Ron Wheeler
<rwhee...@artifact-software.com
<mailto:rwhee...@artifact-software.com>> wrote:
Are you thinking of using OpenAPI(Swagger) to do the documentation?
Ron
On 05/06/2017 10:14 AM, Rafael Weingärtner wrote:
This might be a good excuse for an ACS 5.0! Maybe with some
other additions
such as the support for OASIS CAMP or TOSCA?
It would be interesting to have a ROADMAP with these
desires/wishes.
On Mon, Jun 5, 2017 at 8:52 AM, Simon Weller
<swel...@ena.com.invalid>
wrote:
+1. Echoing what Rohit pointed out, we have a lot of
cleanup to do :-) It
certainly makes it a lot easier though when you're not
breaking
compatibility with existing code.
________________________________
From: Rohit Yadav <rohit.ya...@shapeblue.com
<mailto:rohit.ya...@shapeblue.com>>
Sent: Monday, June 5, 2017 4:04 AM
To: dev@cloudstack.apache.org
<mailto:dev@cloudstack.apache.org>
Subject: Re: [DISCUSS] API versioning
+1 Good idea, though bear in mind there are 500+ APIs with no
modern-RESTful-standardization, a lot of work.
Regards.
________________________________
From: Nitin Kumar Maharana
<nitinkumar.mahar...@accelerite.com
<mailto:nitinkumar.mahar...@accelerite.com>>
Sent: 05 June 2017 12:37:24
To: dev@cloudstack.apache.org
<mailto:dev@cloudstack.apache.org>
Subject: Re: [DISCUSS] API versioning
This looks good. +1
rohit.ya...@shapeblue.com <mailto:rohit.ya...@shapeblue.com>
www.shapeblue.com
<http://www.shapeblue.com><http://www.shapeblue.com
<http://www.shapeblue.com>>
[http://shapeblue.com/wp-content/uploads/2014/03/sungardonline1.jpg
<http://shapeblue.com/wp-content/uploads/2014/03/sungardonline1.jpg>]<
http://www.shapeblue.com/>
Shapeblue - The CloudStack
Company<http://www.shapeblue.com/ <http://www.shapeblue.com/>>
www.shapeblue.com <http://www.shapeblue.com>
The city of Prague was the venue for the spring meeting of
the Cloudstack
European user group. There was
53 Chandos Place, Covent Garden, London WC2N 4HSUK
@shapeblue
On 04-Jun-2017, at 2:34 PM, Rene Moser
<m...@renemoser.net <mailto:m...@renemoser.net>> 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/<version>
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?
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.
--
Ron Wheeler
President
Artifact Software Inc
email: rwhee...@artifact-software.com
<mailto:rwhee...@artifact-software.com>
skype: ronaldmwheeler
phone: 866-970-2435, ext 102 <tel:866-970-2435%2C%20ext%20102>
--
Ron Wheeler
President
Artifact Software Inc
email: rwhee...@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
