CloudStack API编程指引

peiyuan1030

　　原文地址：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/中的接口。
　　
　　
　　修改已存在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个版本去除该参数。