API设计

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秒的延迟重试，在有幂等要求的场景下，不能使用重试
服务降级：对于有依赖的服务，在请求依赖服务发生异常时，不进行依赖服务重试，而是指向本地的一个降级服务保证服务请求的完整性和正确性【有兴趣可以了解阿里巴巴双十一是如何去服务降级】