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（新增/更新/删除 命令）

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/<your plugin>中的接口。

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