RESTful API

REST的出处

Roy Fielding的毕业论文。他是HTTP协议（1.0版和1.1版）的主要设计者、Apache服务器软件的作者之一、Apache基金会的第一任主席。
论文地址：
Architectural Styles and the Design of Network-based Software Architectures
REST章节：
Fielding Dissertation: CHAPTER 5: Representational State Transfer (REST)

RESTful API

是么是API

API （Application Programming Interface,应用程序编程接口），通俗一点说就是一个服务可以提供一些 API，供外部程序调用。举个例子，比如你可以在淘宝app中把商品信息分享到微信、或者微博，在这里微信、微博是api的提供者，淘宝app是api的调用者。

什么是REST

REST 是 REpresentational State Transfer 的缩写，中文直译：表现层状态转移。里面每个字都认识，但是合起来就不知道说了啥。
之所以难以理解是因为前面主语被去掉了，全称是 Resource Representational State Transfer：通俗来讲就是：资源在网络中以某种表现形式进行状态转移。
分解开来：Resource：资源，即数据或者服务。
比如 projects，persons等；
Representational：某种表现形式，比如用JSON，XML，JPEG等；
State Transfer：状态变化。通过HTTP动词实现。
REST-ful,其中ful代表形容词，如helpful,powerful。这类形容词意为"full of,having the quality of"。多加在名词之后表示“充满…的、易于…、可…的、富有…的、具有…的”的意思，是最常用的形容词后缀，反义词后缀是-less。REST和 RESTful说的是一件事情。
要更好的理解REST，我们又必须提到Web，因为REST是以Web为平台的。

什么是Web

分布式信息系统为超文本文件和其它对象（资源）提供访问入口。
资源是Web架构关键点，需要3个操作：识别（identify）、表示（represent）、交互（interact with），通过这三个操作，又引出三个概念。
Uri（统一资源标识符，包括url和urn）识别资源；
Representation（例如html、xml、图片、视频等）表示资源；
通过协议（例如http、https等）与资源进行交互。
REST系统通常是通过HTTP协议，并且使用HTTP的GET、POST、PUT、DELETE等动词来收发数据。

最佳实践：

1. 协议

API与用户的通信协议，推荐使用HTTPS协议。

2. 域名

应该尽量将API部署在专用域名之下。
https://api.example.com
如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。
https://example.org/api/

3. 版本号

应该将API的版本号放入URL
https://api.example.com/v1
或者把版本号放在HTTP头信息中。

4. 网址

每个网址代表一个资源，网址中不能有动词，只能有名词，名词往往和数据库表对应，通常使用名词复数。
BAD
• /getProduct?id=1
• /listOrders
• /createOrder
• /updateOrder
• /deleteOrder?id=1
GOOD
• GET /products: 返回所有产品列表
• POST /products : 创建一个产品
• GET /products/4 : 获取产品4的信息
• PATCH/PUT /products/4 : 修改产品4的信息
• DELETE /products/4: 删除产品4
资源的地址推荐用嵌套结构
资源名称使用组ID和资源ID分层组织，以斜杠（译者注：/，下同）分割。如果某个资源包含子资源，子资源的名称为：父资源名称，斜杠，子资源ID。
例如： //api.example.com/v1/accounts/1/orders/2 账号1下面的订单2信息

API资源名称	组ID	资源ID	组ID	资源ID
//api.example.com/v1	/accounts	account-id	orders	order-id

5. HTTP动词

对于资源的具体操作类型，由HTTP动词表示。

常用的HTTP动词有下面五个（括号里是对应的SQL命令）。

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。

还有两个不常用的HTTP动词。

HEAD：获取资源的元数据。
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

接口方法名与HTTP动词的对应关系：

方法	HTTP 方法映射	HTTP 请求体	HTTP 返回体
list	GET <集合URL>	空	资源* 列表
get	GET <资源URL>	空	资源*
create	POST <集合URL>	资源	资源*
update	PUT or PATCH <资源URL>	资源	资源*
delete	DELETE <资源URL>	空	空**

修改部分资源使用HTTP PATCH，修改完整的资源使用HTTP PUT

6. 过滤信息（Filtering）

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

下面是一些常见的参数。

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

7. 状态码（Status Codes）

使用正确的HTTP状态码来表示操作结果
常见的操作码：
200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - []：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - []：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - []：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

8. 错误处理（Error handling）

如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。
{ error: "params is invalid,please check you request!" }

9. 其他

API 的身份认证应该使用 OAuth 2.0 框架；
REST API 应该接受 JSON 作为请求负载，并发送 JSON 响应，避免使用 XML。

参考资料

https://www.ruanyifeng.com/blog/2014/05/restful_api.html
https://www.zhihu.com/question/28557115/answer/48094438
https://cloud.google.com/apis/design/resources
https://en.wikipedia.org/wiki/Representational_state_transfer
https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/
https://www.rfc-editor.org/rfc/pdfrfc/rfc7231.txt.pdf