前言
本文阐述为CloudStack编写新API或者更新已存在API时应遵循的约定和编程指引。
参考文档
(暂略)
介绍
当你需要为CS添加新的API时，需要创建一个Request类和Response类(或者在扩展CS API功能时它的API Responese已经定义的情况下重用已经存在的API Response类)。
编写CS API Request类
1、request继承自*Cmd抽象类
CUD(新增/更新/删除 命令)
R(读取列表)命令
重要-从2.x开始，新的CUD API命令不再继承自BaseCmd 类，它们被看做是异步命令，继承自BaseAsyncCmd或者BaseAsyncCreateCmd。
扩展BaseAsyncCmd或者BaseAsyncCreateCmd，创建新的CS实体命令扩展BaseAsyncCreateCmd，UD命令扩展BaseAsyncCmd。
2、新添加的command类应以“*Cmd”结尾且标注@ApiCommand。更多请阅参考文档Annotations use in the API中的@ parameters。
3、定义所有的请求参数，且所有的都用@Parameter标注。
4、为RUD命令实现execute()方法，为R命令实现execute()/create()。
5、增加s_name--响应的名字，并且为小写。
6、在为命令命名时，根据含义优先使用create/delete/update/list，只有当这些前缀不能满足你的逻辑时才考虑用你自己的(如assign)。
编写CS API Response类
1、让你的类继承自BaseResponse。
2、用@EntityReference标注Response类，并设定关联的CloudStack接口，它是你返回给API用户的对象。比如VolumeResponse 用EntityReference 标注关联Volume接口。
3、将每个参数用@SerializedName 和 @Param注解。 请阅在Annotations use in the API中关于这些注解的细节。
4、参数名称都是小写。
5、确保没有将真实的DB id设置到id字段将其暴漏，请用UUID值代替。
API位置和注册
命令的位置取决于该命令将是可用/禁用插件或者CloudStack核心的一部分。
当命令是CS核心的一部分
位置：Reque/Response代码放在cloud-api/cloud-engine-api下。
访问权限：命令的访问控制权限(谁有能调用它)在commands.properties.in里注册。
命令注册：命令应添加到CS支持的所有的API列表中，该列表由ManagementServerImpl.getCommands()获得
注意当命令调用完成时，它们关联的只能是cloud-api 或 cloud-util包里的接口
当命令是插件/服务的一部分
位置：Reque/Response代码放在plugin包下。
访问权限：在Cmd文件里定义权限，使用@APICommand 注解"authorized"字段，如authorized = {RoleType.Admin}) 。
命令注册：让插件管理类继承自PluggableService 接口，增加到命令列表的命令由getCommands()返回。
定义在插件中的命令只关联位于cloud-api/cloud-utils/中的接口。
修改已存在API的规则
1、对Request：不要将参数从可选改为必需的；
2、对Request：不要在已存在的命令里增加一个required=true的参数；
3、对Request：不要降低command的权限，从对普通用户可用降到只对管理员可用；
4、对Request/Response：不要重命名已有的参数；
5、对Request/Response：不要更改参数的类型(如从String改为Map)
6、对Response：不要删除Response的参数，由于第三方软件会依赖它。
其它规则：
1、当新增一个参数时，应该在它的@Parameter 里标注"since=release #" 字段；
2、如果你认为有些参数会在未来被删除掉，请标注@Deprecated，并确保在第n版本里记录。当它发布后，客户有机会去检查/修改代码以去掉这个参数。于是可以在第n+1个版本去除该参数。
