API设计
Google API 设计思想
1、设计
-
API设计原则
- 简单
- 可用
- 一致
-
HTTP 常用方法
- get 获取
- put 更新
- post 添加
- delete 删除
- patch 更新
Http patch 与 put 的区别：
PATCH方法是新引入的，是对PUT方法的补充，用来对已知资源进行局部更新；对于上述语句的理解：使用put方法会在提交的时候提交整个module，网络传输量大；patch在提交的时候只会提交你期望传输的属性；http 的不同的方法是对restful设计的一个简单的约定，并非强制，只为了更加贴近上述API设计原则
- restFul Api 常用方法
- get
- list
- delete
- update
- add
对于某个实体的CRUD操作可以通过http的不同请求方法， 来调用相同方法名称的不同实现接口；
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;
// 要创建的书籍资源，客户端绝不能设置‘Book.name’属性
Book book = 2;
}
- 自定义方法：自定义方式使用 名词:动词
String url = "books/book:getBatch"
url = "books/book:undelete"
在Http 的请求中，有一些场景有着严格幂等的要求，关于幂等相关的参见：架构笔记
2、标准字段(引自https://github.com/archnotes/gitbook)
本节描述了在需要类似概念时应使用的一组标准消息字段定义。 这将确保相同的概念在不同的API上具有相同的名称和语义。
| 字段名 | 类型 | 描述 |
|---|---|---|
| name | string | name字段应该包含相对资源名 |
| parent | string | 对于资源定义和List/Create请求，parent字段应包含父级相对资源名
|
| create_time | Timestamp | 一个实体的创建时间戳 |
| update_time | Timestamp | 一个实体的最后更新时间戳；注意update_time会被create/patch/delete等操作更新 |
| delete_time | Timestamp | 实体的删除时间戳，仅当支持保留时。 |
| time_zone | string | 时区名，它应该符合IANA时区标准，如"America/Los_Angeles"。 有关详细信息，请参阅 https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. |
| region_code | string | 位置的Unicode国家/地区代码（CLDR），例如“US”和“419”。 有关详细信息，请参阅 http://www.unicode.org/reports/tr35/#unicode_region_subtag。 |
| language_code | string | BCP-47语言代码，如“en-US”或“sr-Latn”。 有关详细信息，请参阅http://www.unicode.org/reports/tr35/#Unicode_locale_identifier。 |
| display_name | string | 一个实体显示的名称。 |
| title | string | 实体的正式名称，例如公司名称。 它应该被视为正规版本的display_name |
| description | string | 一个实体的详细文字描述 |
| filter | string |
List方法的标准过滤参数 |
| query | string | 应用于Search方法的(也就是说 :search)过滤参数 |
| page_token | string |
List请求的数据分页令牌 |
| page_size | int32 |
List请求的数据分页大小 |
| total_size | int32 | 列表中的总条目数，不考虑分页 |
| next_page_token | string |
List返回结果中下一个分页的令牌。它应该在后续请求中传递为page_token参数；空值意味着没有更多数据 |
| request_id | string | 用于检测重复请求的唯一字符串id |
| resume_token | string | 用于恢复流式传输请求的隐含令牌 |
| labels | map<string, string> | 表示云资源的标签 |
| deleted | bool | 如果资源允许取消删除，则它必须有deleted字段表示资源是否已被删除 |
| show_deleted | bool | 如果资源允许取消删除，相应的List方法必须有一个show_deleted字段，以便客户端发现已删除的资源。 |
| validate_only | bool | 如果为true，则表示给定的请求仅需要被检验，而不是被执行。 |
3、通用返回
{
'status':1,
'message':''
'code':9991,
'detail':'详情'
'data':Object
}
4、错误重试，服务降级
客户端对于错误的处理：500 错误最小延迟应为1s，429错误【服务器资源紧张】客户端可能会以最少30秒的延迟重试，在有幂等要求的场景下，不能使用重试
服务降级：对于有依赖的服务，在请求依赖服务发生异常时，不进行依赖服务重试，而是指向本地的一个降级服务保证服务请求的完整性和正确性【有兴趣可以了解阿里巴巴双十一是如何去服务降级】
