前言

本文闡述為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個版本去除該參數。

總結

以上是生活随笔為你收集整理的cloudstack java api_CloudStack API编程指引的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。