前言
本文阐述为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个版本去除该参数。