REST API設計指導——譯自Microsoft REST API Guidelines(三)

前面咱們說了,若是API的設計更規範更合理,在很大程度上可以提升聯調的效率,下降溝通成本。那麼什麼是好的API設計?這裏咱們不得不提到REST API。數據庫

關於REST API的書籍不少,可是完整完善實踐豐富的設計指導並很少見,咱們有幸看到了微軟團隊的做品——Microsoft REST API Guidelines,所以纔有了此篇內容。因爲公衆號文章內容字數有限,所以咱們將翻譯稿拆分並分享出來,而且給出英文對照。翻譯的不對之處,請多多指教。安全

另外,因爲本週聚焦在架構層面,下週咱們爭取錄製更多教程並分享出來。網絡

 

5 Taxonomy 分類

 

As part of onboarding to Microsoft REST API Guidelines, services MUST comply with the taxonomy defined below.架構

Microsoft REST API 準則基本要求的一方面就是 服務的分類必須符合如下定義。app

 

5.1 Errors 錯誤

Errors, or more specifically Service Errors, are defined as a client passing invalid data to the service and the servicecorrectly rejecting that data.異步

錯誤,或更具體的服務錯誤,被定義爲客戶端將無效數據傳遞給服務而且服務明確地拒絕該數據。async

 

Examples include invalid credentials, incorrect parameters, unknown version IDs, or similar.ide

例如,無效的證書,錯誤的參數,未知的版本 ID 等。性能

 

These are generally "4xx" HTTP error codes and are the result of a client passing incorrect or invalid data.ui

客戶端傳遞錯誤的或者不合法的數據的狀況一般返回 「4xx」 的 HTTP 錯誤代碼。

 

Errors do not contribute to overall API availability.

錯誤不會影響總體 API 的可用性。

 

譯者注:錯誤能夠理解成客戶端參數錯誤,一般返回「4XX」狀態碼,並不影響總體的API使用。

 

5.2 Faults  故障

Faults, or more specifically Service Faults, are defined as the service failing to correctly return in response to a valid client request.

故障, 或更具體地說服務故障被定義爲服務沒法正確返回數據以響應有效的客戶端請求。

These are generally "5xx" HTTP error codes.

一般會返回 「5xx」 HTTP 錯誤代碼。

Faults do contribute to the overall API availability.

故障會影響總體 API 的可用性。

Calls that fail due to rate limiting or quota failures MUST NOT count as faults.

因爲速率限制或配額不足致使失敗的調用毫不能算做故障。

Calls that fail as the result of a service fast-failing requests (often for its own protection) do count as faults.

因爲服務 fast-failing 請求而失敗的調用(一般是爲了保護本身)會被視爲故障。

 

譯者注:故障意味着服務端代碼出現故障,可能會影響總體的API使用。好比數據庫鏈接超時。

fast-failing   快速失敗

safe-failing 安全失敗

 

 

5.3 Latency 延遲

Latency is defined as how long a particular API call takes to complete, measured as closely to the client as possible.

延遲定義爲具體 API 被調用完成所需的時長, 儘量使用客戶端調用進行測量。

 

This metric applies to both synchronous and asynchronous APIs in the same way.

這種測量方法一樣適用於同步和異步 的API。

 

For long running calls, the latency is measured on the initial request and measures how long that call (not the overall operation) takes to complete.

對於長時間運行的調用,延遲定義爲第一次調用它所需的時長,而非它長時間運行的時長。

 

譯者注:Latency(延遲)是衡量軟件系統的最多見的指標之一,不單單和系統、架構的性能相關,還和網絡傳輸和延遲有關係。

 

5.4 Time to complete 完成時間

Services that expose long operations MUST track "Time to Complete" metrics around those operations.

暴露長時間操做的服務必須跟蹤這些操做的 "完成時間" 指標。

 

5.5 Long running API faults 長時間運行的API故障

For a Long Running API, it's possible for both the initial request to begin the operation and the request to retrieve the results to technically work (each passing back a 200), but for the underlying operation to have failed.

對於長時間運行的 API,極可能出現初始請求成功,且後續每次去獲取結果時 API 也處於正常運行(每次都回傳 200)中,但其底層操做已經失敗了的狀況。

 

Long Running faults MUST roll up as Faults into the overall Availability metrics.

長時間運行故障必須做爲故障彙總到整體可用性指標中。

相關文章
相關標籤/搜索