CloudStack API编程指引

原文地址:https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+API+Coding+Guidelines

前言

本文阐述为CloudStack编写新API或者更新已存在API时应遵循的约定和编程指引。

参考文档

 (暂略)

介绍

当你需要为CS添加新的API时,需要创建一个Request类和Response类(或者在扩展CS API功能时它的API Responese已经定义的情况下重用已经存在的API Response类)。

编写CS API Request类

1、request继承自*Cmd抽象类

CUD(新增/更新/删除 命令)

CloudStack API编程指引

R(读取列表)命令

 

CloudStack API编程指引

重要-从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包里的接口

CloudStack API编程指引

 

当命令是插件/服务的一部分

  • 位置:Reque/Response代码放在plugin包下。
  • 访问权限:在Cmd文件里定义权限,使用@APICommand 注解"authorized"字段,如authorized = {RoleType.Admin}) 。
  • 命令注册:让插件管理类继承自PluggableService 接口,增加到命令列表的命令由getCommands()返回。

定义在插件中的命令只关联位于cloud-api/cloud-utils/<your plugin>中的接口。

CloudStack API编程指引

 

修改已存在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个版本去除该参数。

 

你可能感兴趣的:(CloudStack)