API設(shè)計(jì)
Google API 設(shè)計(jì)思想
1、設(shè)計(jì)
-
API設(shè)計(jì)原則
- 簡單
- 可用
- 一致
-
HTTP 常用方法
- get 獲取
- put 更新
- post 添加
- delete 刪除
- patch 更新
Http patch 與 put 的區(qū)別：
PATCH方法是新引入的，是對PUT方法的補(bǔ)充，用來對已知資源進(jìn)行局部更新；對于上述語句的理解：使用put方法會在提交的時候提交整個module，網(wǎng)絡(luò)傳輸量大；patch在提交的時候只會提交你期望傳輸?shù)膶傩?；http 的不同的方法是對restful設(shè)計(jì)的一個簡單的約定，并非強(qiáng)制，只為了更加貼近上述API設(shè)計(jì)原則
- restFul Api 常用方法
- get
- list
- delete
- update
- add
對于某個實(shí)體的CRUD操作可以通過http的不同請求方法， 來調(diào)用相同方法名稱的不同實(shí)現(xiàn)接口；
service LibraryService {
rpc GetBook(GetBookRequest) returns (Book) {
option (google.api.http) = {
get: "/v1/{name=shelves/*/books/*}"
};
};
rpc CreateBook(CreateBookRequest) returns (Book) {
option (google.api.http) = {
post: "/v1/{parent=shelves/*}/books"
body: "book"
};
};
}
message Book {
//書的資源名稱。格式必須是："shelves/*/books/"
//比如："shelves/shelf1/books/book2"。
string name = 1;
// ... 其他屬性
}
message GetBookRequest {
//書的資源名稱。"shelves/shelf1/books/book2"。
string name = 1;
}
message CreateBookRequest {
// 新建書的父資源的資源名稱
// 比如"shelves/shelf1".
string parent = 1;
// 要創(chuàng)建的書籍資源，客戶端絕不能設(shè)置‘Book.name’屬性
Book book = 2;
}
- 自定義方法：自定義方式使用 名詞:動詞
String url = "books/book:getBatch"
url = "books/book:undelete"
在Http 的請求中，有一些場景有著嚴(yán)格冪等的要求，關(guān)于冪等相關(guān)的參見：架構(gòu)筆記
2、標(biāo)準(zhǔn)字段(引自https://github.com/archnotes/gitbook)
本節(jié)描述了在需要類似概念時應(yīng)使用的一組標(biāo)準(zhǔn)消息字段定義。 這將確保相同的概念在不同的API上具有相同的名稱和語義。
| 字段名 | 類型 | 描述 |
|---|---|---|
| name | string | name字段應(yīng)該包含相對資源名 |
| parent | string | 對于資源定義和List/Create請求，parent字段應(yīng)包含父級相對資源名
|
| create_time | Timestamp | 一個實(shí)體的創(chuàng)建時間戳 |
| update_time | Timestamp | 一個實(shí)體的最后更新時間戳；注意update_time會被create/patch/delete等操作更新 |
| delete_time | Timestamp | 實(shí)體的刪除時間戳，僅當(dāng)支持保留時。 |
| time_zone | string | 時區(qū)名，它應(yīng)該符合IANA時區(qū)標(biāo)準(zhǔn)，如"America/Los_Angeles"。 有關(guān)詳細(xì)信息，請參閱 https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. |
| region_code | string | 位置的Unicode國家/地區(qū)代碼（CLDR），例如“US”和“419”。 有關(guān)詳細(xì)信息，請參閱 http://www.unicode.org/reports/tr35/#unicode_region_subtag。 |
| language_code | string | BCP-47語言代碼，如“en-US”或“sr-Latn”。 有關(guān)詳細(xì)信息，請參閱http://www.unicode.org/reports/tr35/#Unicode_locale_identifier。 |
| display_name | string | 一個實(shí)體顯示的名稱。 |
| title | string | 實(shí)體的正式名稱，例如公司名稱。 它應(yīng)該被視為正規(guī)版本的display_name |
| description | string | 一個實(shí)體的詳細(xì)文字描述 |
| filter | string |
List方法的標(biāo)準(zhǔn)過濾參數(shù) |
| query | string | 應(yīng)用于Search方法的(也就是說 :search)過濾參數(shù) |
| page_token | string |
List請求的數(shù)據(jù)分頁令牌 |
| page_size | int32 |
List請求的數(shù)據(jù)分頁大小 |
| total_size | int32 | 列表中的總條目數(shù)，不考慮分頁 |
| next_page_token | string |
List返回結(jié)果中下一個分頁的令牌。它應(yīng)該在后續(xù)請求中傳遞為page_token參數(shù)；空值意味著沒有更多數(shù)據(jù) |
| request_id | string | 用于檢測重復(fù)請求的唯一字符串id |
| resume_token | string | 用于恢復(fù)流式傳輸請求的隱含令牌 |
| labels | map<string, string> | 表示云資源的標(biāo)簽 |
| deleted | bool | 如果資源允許取消刪除，則它必須有deleted字段表示資源是否已被刪除 |
| show_deleted | bool | 如果資源允許取消刪除，相應(yīng)的List方法必須有一個show_deleted字段，以便客戶端發(fā)現(xiàn)已刪除的資源。 |
| validate_only | bool | 如果為true，則表示給定的請求僅需要被檢驗(yàn)，而不是被執(zhí)行。 |
3、通用返回
{
'status':1,
'message':''
'code':9991,
'detail':'詳情'
'data':Object
}
4、錯誤重試，服務(wù)降級
客戶端對于錯誤的處理：500 錯誤最小延遲應(yīng)為1s，429錯誤【服務(wù)器資源緊張】客戶端可能會以最少30秒的延遲重試，在有冪等要求的場景下，不能使用重試
服務(wù)降級：對于有依賴的服務(wù)，在請求依賴服務(wù)發(fā)生異常時，不進(jìn)行依賴服務(wù)重試，而是指向本地的一個降級服務(wù)保證服務(wù)請求的完整性和正確性【有興趣可以了解阿里巴巴雙十一是如何去服務(wù)降級】
