根据REST APIs的成熟度模型 ，此规范关注的是Level 2的APIs。

1 设计指南

HTTP APIs主要由四部分组成 : #HTTP, #URL, 资源，资源的表述。

资源的表述通常都采用#JSON格式，故而下文使用#JSON代指资源的表述。

根据这些组成部分，按照以下3个步骤设计APIs。

1.1 基于资源设计API

设计HTTP APIs的首要任务是识别出业务领域中的资源。资源是对服务端提供的服务进行分解、组合后的一个被命名的抽象概念。

有很重要一点需要明确 : 资源≠数据表，它们两个之间并没有直接的映射关系。如果直接把数据存储结构映射为资源，则只会让资源无法有效的表达业务需要，也会造成资源本身和底层存储的紧耦合。

资源的设计是以名词为中心的。比如今天的天气是一个资源; 而获取今天的天气则不是，它代表的是对今天的天气资源的一个读取操作。基于此我们可以抽象出来一个天气的资源。

1.2 基于URL标识资源

识别出资源后，则需要为其分配一个#URL进行标识。

1. 一个资源可以有多个#URL。
2. 一个#URL只能标识一个资源。

总结来说就是资源 : URL的关系就是1 : N的关系。

比如上面提到的天气和今天的天气这两个资源，可以用如下的#URL进行标识。

资源名(资源的名字)体现在#URL中的Path部分。

关于资源名采用单数还是复数的问题，这里统一为单数（即使代表的是一个集合资源）。原因有 3 :

1. 一致性 : 中文中并无复数的概念，可保持一致。
2. 无二义性 : 比如news，既是单数也是复数。所以就不必追求它们的单数或者复数形式形式；基于同样的原则，那么原本就是单数的名词，也无需刻意追求复数形式。
3. 简单性 : 英文名词的复数形式并不统一（比如order > orders, history > histories）,使用单数可以避免团队成员对于这些差异的不同理解与争执。

资源存在子资源的情况下，可以把子资源提升为顶层的资源。比如有一个订单资源/order/{order_id}，订单中包含2件物品。

# 不推荐 单个子资源
/order/{order_id}/item/{item_id}

# 推荐 单个子资源
/order-item/{order_item_id}

# 推荐 子资源集合
/order/{order_id}/item

1.3 基于HTTP和JSON操作URL标识的资源

在标识出资源以后，就可以使用#HTTP通过#JSON来操作资源了。

1. 使用#HTTP Method来映射对资源的操作请求（CRUD或者其他）。
2. 使用#HTTP Header携带请求/响应所需的元数据信息。
3. 使用#HTTP Stauts Code表示HTTP协议层面的响应状态。
4. 使用#JSON作为数据交换格式。

2 URL

URL遵循RFC3986规范，由以下几部分组成。

  https://api.linianhui.test:8080/user/disabled?first_name=li#title
  \___/  \______________________/\_____________/\___________/\____/
    |               |                   |             |          |
  scheme        authority              path         query    fragment

URL的命名规则#URL命名规则。

参考资料 :

1. https://tools.ietf.org/html/rfc3986

3 HTTP

3.1 HTTP Method

面向资源设计的HTTP APIs中，绝大部分的操作都是CRUD(Create,Read,Update,Delete)，都可以映射为某一个HTTP Method。其余的无法映射的操作一般存在两种解决方案 :

1. 抽象出新的资源，比如禁用用户的操作。假设用户的资源是/user，那么可以抽象出来一个被锁定的用户的资源/user/disabled。如此以来，
   1. 禁用用户 : POST /user/disabled或者PUT /user/disabled/{user_id}。
   2. 取消禁用 : DELETE /user/disabled/{user_id}。
   3. 获取被禁用的用户列表 : GET /user/disabled。
2. 如果上面的方式无法满足需要，则可以采用POST和URL/动词的组合。还拿上面的举例 :
   1. 禁用用户 : POST /user/{user_id}/disable或者PUT /user/{user_id}/disable。
   2. 取消禁用 : DELETE /user/{user_id}/disable。
   3. 获取被禁用的用户列表 : GET /user?status=DISABLED。

3.1.1 Names

PATCH和POST都是不安全且不幂等的，差异在于PATCH仅是用于部分更新资源, 而且是一个可选支持的HTTP Method，可能会存在一些代理、网关等组件不支持的情况，所以推荐用POST来代替它。

3.1.2 Semantics

每一个HTTP Method都具有一下3个HTTP协议层面的语义。

参考资料 :

1. https://tools.ietf.org/html/rfc7231#section-4
2. https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods

3.2 HTTP Header

Http Header的用途在于携带HTTP Request和HTTP Response的元数据信息。

格式为Name:Value : Name不区分大小写，通常都采用首字母大写，-分隔的写法，比如Content-Type。按其用途可以分为如下4类 :

1. 通用类 : 描述请求和响应的。
2. 请求类 : 描述请求的。
3. 响应类 : 描述响应的。
4. 表述类 : 描述请求和响应的Body部分的。

HTTP APIs中常用到的Headers :

HTTP Request:

POST /xxx HTTP/1.1
Accept: application/json;
Accept-Charset: utf-8
Content-Type: application/json;charset=utf-8

{
  "x":1,
  "y":2
}

HTTP Response:

HTTP/1.1 201 Created
Content-Type: application/json;charset=utf-8
Content-Encoding: gzip
Location: /xxx/1
Request-Id: {id}

Request-Id可以由Http Request传入，也可以由服务端生成，追加此信息到log中，便于服务端追踪请求。

参考资料 :

1. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers
2. https://tools.ietf.org/html/rfc7231#section-5
3. https://tools.ietf.org/html/rfc7231#section-7

3.3 HTTP Stauts Code

HTTP Status Code用来指示HTTP协议层面的请求状态。它由一个数字和一个描述消息构成，比如200 OK。有以下几类状态码 :

1. 2xx : 执行成功。
2. 4xx : 客户端的错误，通常情况下客户端需要修改请求然后再次发送请求。
3. 5xx : 服务端的错误。

参考资料 :

1. https://tools.ietf.org/html/rfc7231#section-6
2. https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
3. https://httpstatuses.com/

3.4 HTTP Error Response

虽然#HTTP Stauts Code有4xx和5xx的状态码来表示哪里出错了，但是其代表的只是HTTP协议层面的错误描述，它无法提供和业务相关的更具体错误描述。基于此种情况，我们需要设计一套描述业务层面错误的数据结构 :

{
  "method": "POST",
  "url": "/book",
  "statusCode": 400,
  "errors": [
    {
      "code": "name",
      "value": null,
      "message": "书名不能为空。"
    },
    {
      "code": "price",
      "value": -1,
      "message": "价格不能为负数"
    }
  ],
  "extra": null
}

以上这个数据结构仅在状态码为4xx和5xx出现的时候才会使用；2xx的时候则不包含此数据结构。

code字段可以是一些出错的字段名、某一错误类别（比如NO_PERMISSION这种全局唯一的常量字符串）等等。

{
  "method": "DELETE",
  "url": "/book/1",
  "statusCode": 403,
  "errors": [
    {
      "code": "NO_PERMISSION",
      "value": "BOOK:DELETE",
      "message": "没有BOOK:DELETE的权限"
    }
  ],
  "extra": null
}

参考资料 :

1. Problem Details for HTTP APIs : https://tools.ietf.org/html/rfc7807

4 JSON

JSON是一种应用非常广泛的数据交换格式。其包含6种基本的数据类型。

1. JSON的命名规则#JSON命名规则。
2. JSON中没有原生的日期和时间类型，应该遵循#Date Time的要求，使用string类型表示。
3. JSON中出现的和国际化相关的数据遵循#i18n中的要求。
4. null值的字段不能忽略掉，应该显式的表示为"field_name":null。

JSON示例 :

{
  "first_name": "li",
  "lase_name": "nianhui",
  "gender": "MALE",
  "age": 123,
  "tags": ["coder"],
  "is_admin": true,
  "address": null,
  "country_code":"CN",
  "currency_code":"CNY",
  "language_code":"zh",
  "locale_code":"zh-CN",
  "created_at":"2018-01-02T03:04:05.128Z+08:00",
  "time_zone":"+08:00"
}

参考资料 :

1. http://json.org/
2. https://tools.ietf.org/html/rfc7159

5 版本化

在Level 2的HTTP APIs中，虽然我们推荐也努力使得我们的APIs不做不兼容的改动，但是依然无法彻底的避免不兼容的升级。这就使得我们不得不对APIs进行版本化管理。通常有以下 3 种方案 :

1. URL

   GET http://api.linianhui.com/v1/weather HTTP/1.1
   

2. Request Header

   GET http://api.linianhui.com/weather HTTP/1.1
   Api-Version: v1
   

3. Request Header (Accept Header)

   GET http://api.linianhui.com/weather HTTP/1.1
   Accept: application/vnd.v1+json
   

在Level 2的API中优先推荐使用方案1(URL)。理由是其更直观，便于实现，便于日志追踪。

6 命名规则

6.1 URL

URL的query部分是name=value而不是key=value，URL支持name重复存在，Web服务端框架绝大部分都支持直接映射为数组。

此外命名规则约束的是name部分，而不关心value部分，value部分应该采用urlencode进行编码。示例 :

https://api.my-server.com/v1/user-stories?dipplay_names=abc&display_names=efg

服务端会得到一个类型为数组的dispaly_names参数。

display_names = [
  "abc",
  "efg"
];

6.2 JSON

ENUM_FILED_VALUE用于表示枚举字段，用全大写和_分隔符，以示和普通的字符串进行区分。示例 :

{
  "first_name":"li",
  "lase_name":"nianhui",
  "gender":"MALE",
  "remark":"描述信息",
  "age":1234
}

参考资料 :

1. https://support.google.com/webmasters/answer/76329
2. https://stackoverflow.com/questions/5543490/json-naming-convention
3. https://tools.ietf.org/html/rfc3986#section-2.4

7 Date Time

日期和时间采用RFC3339中定义的通用的格式。表示方法如下 :

扩展 : date-fullyear-month(年月)可表示为date-fullyear-date-month，比如2018-04。

1. 日期和时间应该满足上面表格中定义的格式。
2. 优先采用UTC时间（即Z+00:00）。即使没有跨时区的要求，也必须携带时区偏移信息，比如2018-04-01T02:08:59.256Z+08:00。

参考资料 :

1. Date and Time Formats - ISO 8601 : https://www.w3.org/TR/NOTE-datetime
2. Date and Time on the Internet: Timestamps ( RFC 3339 ) : https://tools.ietf.org/html/rfc3339#section-5.6

8 i18n

国家代码 : 采用Country CodeISO 3166 alpha-2版本（2个字母）。示例 :

1. 中国 : CN
2. 美国 : US
3. 其他 : https://en.wikipedia.org/wiki/ISO_3166-2#Current_codes

货币代码 : 采用Currency CodeISO 4217:2015版本（3个字母）。示例 :

1. 人民币 : CNY
2. 美元 : USD
3. 其他 : https://en.wikipedia.org/wiki/ISO_4217#Active_codes

语言代码 : 采用Language CodeISO 639-1:2002版本（2个字母）。示例 :

1. 中文 : zh
2. 英文 : en
3. 其他 : https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

区域代码 : 由Language Code和Country Code组合而成。示例 :

1. zh-CN
2. en-US

参考资料 :

1. https://www.iso.org/iso-3166-country-codes.html
2. https://www.iso.org/iso-4217-currency-codes.html
3. https://www.iso.org/iso-639-language-codes.html

9 其他

待完善...

9.1 HTTP Request 公共查询参数

示例:

GET /user
    ?page=2
    &page_size=10
    &sort=name,age desc
    &created_at_begin=2018-01-01
    &created_at_end=2018-06-01

上面的查询代表的含义 : 按照name升序和age倒序的排序方式；获取created_at时间位于2018-01-01和2018-06-01区间内；按照每页10条数据，获取第2页的数据。

9.2 HTTP Response 分页数据结构

在分页请求的时候，API会返回分页后的数据和分页的信息。

{
  "page": 2,
  "page_size": 10,
  "total_count": 100,
  "items":[
    {...},
    {...},
  ]
}

10 示例

... 待补充

11 参考资料

本人的解读REST系列博客 : 理解REST

REST APIs 成熟度模型 : https://martinfowler.com/articles/richardsonMaturityModel.html

PayPal的API设计指南 : https://github.com/paypal/api-standards

REST架构风格的出处 : 架构风格与基于网络的软件架构设计(by Roy Thomas Fielding)论文。

1. 英文版 : https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
2. 中文版 : https://www.infoq.cn/article/web-based-apps-archit-design/

HTTP APIs 四大组成部分（HTTP, URI, MIME, JSON）

1. HTTP/1.1 ( RFC7230-7235 ) : https://tools.ietf.org/html/rfc7230
2. URI ( RFC 3986 ) : https://tools.ietf.org/html/rfc3986
3. MIME ( RFC 2387 ) : https://tools.ietf.org/html/rfc2387
4. JSON : http://json.org/

Hypermedia

1. JSON Schema: http://json-schema.org/

URL模板

1. URI Template ( RFC6570 ) : https://tools.ietf.org/html/rfc6570

彩蛋：NO SOAP!