原文地址： 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個版本去除該參數。

?

CloudStack API編程指引