RESTful API

RESTful 是目前最流行的 API 设计规范，用于 Web 数据接口的设计。
本文参考 《REST和RESTful浅谈》，《三分钟彻底了解Restful最佳实践》

1.概念

REST 英文全称为：representational state transfer；如果能够理解该词的每一个含义，那么也就能够理解 RESTful 风格的设计。

• 资源（Resources）
  网络上的所有事物都可以被称为资源。它可以是一段文本、一张图片、一首歌曲等等，总之就是一个具体的实在。你可以用一个URI（统一资源定位符）指向它，每种资源对应一个特定的URI。要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。

• 表现层（Representation）
  参考过很多文章，觉得这个 表现层 意译最为能够理解。大概可以理解为，资源呈现出来的形式，叫做它的表现层。比如，文本可以用txt格式表现，也可以用HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式；图片可以用JPG格式表现，也可以用PNG格式表现。

• 状态转化（State Transfer）
  当客户访问一个网站，就代表客户端和服务器进行了一个互动。如果客户端想要操作服务器，必须通过某种手段，让服务器端发生“状态转化”。该转换就是建立在表现层上的，因此就是 “表现层状态转化”。
  在客户端，只能通过HTTP协议来操作资源。四个表示操作方式的动词：GET、POST、PUT、DELETE。它们分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。

2.优点

• 在 RESTful 之前：

1. GET 查询书本数据；
/books/query    
2. POST 新增书本
/book/add      
3. POST 更新书本
/book/update  
4. GET／POST 删除书本
/book/delete 

• 在 RESTful 之后：

1. GET 查询书本数据；
/books   
2. POST 新增书本
/book     
3. PUT 更新书本
/book
4. DELETE 删除书本
/book

• RESTful 更加专注于请求数据指令为 “动词 + 宾语” 的结构；因此，只要更加专注资源项的定义；

动词通常为以下几种：

HTTP方法	含义
GET	读取（Read）
POST	新建（Create）
PUT	更新（Update）
PATCH	更新（Update），通常是部分更新
DELETE	删除（Delete）

宾语：
这里的宾语就是 API 的 URL，就是 HTTP 动词作用的对象。

✅ /books
❌ /getBooks
⚠️ 既然我们知道了URL的宾语是名词，关于单复数的使用，推荐使用复数。
其次，避免多级URL，这样的URL不利于扩展，并且语义也不明确。

3.状态码

HTTP 状态码是一个三位数，分成五个类别：

1xx：相关信息
2xx：操作成功
3xx：重定向
4xx：客户端错误
5xx：服务器错误

这里不多介绍，推荐一篇文章 List of HTTP status codes

就我个人而言，我最喜欢看到的是 200（请求成功啦）；最讨厌看到的是 500（服务器都没办法连上还谈什么成功）；对 404 抱着好奇的心里（路径没找到具体谁错了不得而知）。