翻譯自 api design guide - custom methods此篇文章討論如何在 api 設計中使用自定義方法。
自定義方法指五個標準方法之外的 api 方法。應該（should）只有當標準方法不能完成需要的功能時才使用自定義方法。一般情況下，api 設計者應該（should）在可行的情況下選擇標準方法。標準方法有更簡潔和明確定義的語義並且被大多數開發者熟知，所以它們更易於使用並且不易出錯。另乙個優勢是 api 平台對標準方法的支援更好，比如計費、錯誤處理、日誌和監控。
自定義方法可以被關聯到資源、集合或服務。它可以（may）接收任意請求並返回任意響應，並且也可以支援流式請求與響應。
自定義方法應該（should）使用如下的通用對映方法：
:代替/來分隔資源名與自定義動詞是為了支援任意 path 引數，例如，取消刪除（undelete）檔案能對映為post /files/a/long/file/name:undelete。
選擇 http 對映時必須（shall）遵守如下指南：
警告：如果服務實現多個 api，必須（must）小心地建立服務配置以避免 api 間的自定義動詞衝突。
// 服務級別的自定義方法
rpc watch(watchrequest) returns (watchresponse) ;
}// 集合級別的自定義方法
rpc clearevents(cleareventsrequest) returns (cleareventsresponse) ;
}// 資源級別的自定義方法
rpc cancelevent(canceleventrequest) returns (canceleventresponse) :cancel"
body: "*"
};}// 用於批量 get 的自定義方法
rpc batchgetevents(batchgeteventsrequest) returns (batchgeteventsresponse) ;
}
一些標準方法比自定義方法更好的例子：
常用的自定義方法名稱列表如下。 api 設計者在引入自已的名稱之前應該考慮這些名稱，以便於跨 api 的一致性
| 方法名 | 自定義動詞 | http 動詞 | 備註 |
| - | - | - | - |
| canecl | :cancel | post | 取消未完成的操作（構建、計算等） |
| batchget《複數名詞》 | :batchget | post | 批量取得多個資源（詳情請檢視 list 的描述） |
| move | :move | get | 將資源從乙個父資源移動到另乙個中 |
| search | :search | get | 用於獲取不符合 list 語義的資料 |
| undelete | :undelete | post | 恢復以前刪除的資源，推薦的保留期為30天 |
檢視其他章節
google api設計指南 簡介
這是聯網 api 的通用設計指南。它自 2014 年起在 google 內部使用，是 google 在設計 cloud api 和其他 google api 時遵循的指南。此設計指南在此處共享，以便為外部開發者提供資訊，並使我們所有人更容易協同工作。在設計 grpc api 時，google clo...
Vue入門指南 自定義全域性指令和區域性指令
三 以傳參的方式進行指令設定 四 函式簡寫 當開發需求做乙個自動獲取焦點事件的時候，我們最原生的做法就是通過獲取元素來註冊事件,document.getelementbyid search focus 然而在vue中並不提倡我們直接操作dom元素。那我們該怎麼辦呢？這時候就需要我們自定義指令來實現這...
轉 程式設計師高階學習書籍參考指南 自己的學習路線
初階 基礎知識及入門 01.php與mysql程式設計 第4版 02.深入淺出mysql 資料庫開發 優化與管理維護 第2版 03.實戰nginx 取代apache的高效能web伺服器 04.redis 實戰 06.mongodb權威指南 第2版 07.linux系統命令及shell指令碼實踐指南 ...