RESTful API

前置知识

了解RESTful API 有几个小概念需要知道

1. 资源表现层的状态转移
2. POST的幂等性
3. URL跟URI
4. Rails 跟 REST

推荐书籍 : Rest in Practice

1. 资源表现层的状态转移 (引用网址)

资源（Resources）资源是数据的一种集合.

最大数 3代表着一种资源, 3构成的文件也是另一种资源.
只不过给数据赋予了你想要的意义,所以构成了资源(非严谨)
主要指代互联网上的一个实体，可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。

表现层（Representation）

资源的信息载体形式，叫做表现层。他可以是文本、XML、JSON
或者是一个二进制文件。它的具体表现形式，
应该在HTTP请求的头信息中用Accept和Content-Type字段指定，
这两个字段才是对"表现层"的描述。

一般是JSON

状态转化（State Transfer）

互联网通信协议HTTP协议，是一个无状态协议。
这意味着，所有的状态都保存在服务器端。
因此，如果客户端想要操作服务器，必须通过某种手段，
让服务器端发生"状态转化"（State Transfer）。而这种转化是建立在表现层之上的，
所以就是"表现层状态转化"。

在 HTTP 中，
我们一般通过四种 HTTP动词（verb）来对应资源的变化：

GET用来获取资源，
POST用来新建资源（也可以用于更新资源），
PUT用来更新资源，
DELETE用来删除资源。

相应的状态的交互应当是无状态的（ServerLess）这是 HTTP 的特性所决定的，
要求每次请求包含服务器需要的所有信息，
这样可以很好的确保每一次变化的可预测性，进而提高可靠性，也能增进可扩展性。

小结一下:

（1）每一个URI代表一种资源；

（2）客户端和服务器之间，传递这种资源的某种表现层；

（3）客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。

对照关系:

资源 : URI
表现层 : JSON格式 (资源的 请求/返回 体现)
状态转移 :HTTP动词 (赋予 资源表现层 动作,也可以看做为这个层富有意义)

2. POST的幂等性 (不具备幂等性,引用网址)

幂等 : 在编程中一个幂等操作的特点是其任意多次执行所产生的影响均与一次执行的影响相同。 幂等函数，或幂等方法，是指可以使用相同参数重复执行，并能获得相同结果的函数。 这些函数不会影响系统状态，也不用担心重复执行会对系统造成改变。

在这个REST 中,讲POST幂等性 主要是为了 将 POST 跟 PUT进行分隔开也是为了阐述为什么:

POST是保存操作 , PUT是更新操作

简单例子辅助理解:

//每次都会生成新的资源, 
//多次传输数据一致,但是数据总量发生变化,不满足幂等性
POST http://www.baidu.com/images  

//每次只会对资源进行修改,
//多次传输数据一致,a数据变化跟第一次一样,总量也没有变化,满足幂等性
PUT http://www.baidu.com/images/a

//每次只会对资源进行修改,
//多次传输数据一致,a数据会除了部分更新以外还改变更新次数,总量虽没有变化,但不满足幂等性
PATCH http://www.baidu.com/images/a

3. URL跟URI

引用知乎网友回答

统一资源标志符URI就是在某一规则下能把一个资源独一无二地标识出来。
拿人做例子，
假设这个世界上所有人的名字都不能重复，那么名字就是URI的一个实例，
通过名字这个字符串就可以标识出唯一的一个人。
现实当中名字当然是会重复的，所以身份证号才是URI，通过身份证号能让我们能且仅能确定一个人。

那统一资源定位符URL是什么呢。
也拿人做例子然后跟HTTP的URL做类比，
就可以有：动物住址协议://地球/中国/浙江省/杭州市/西湖区/某大学/14号宿舍楼/525号寝/张三.
这样可以看到，这个字符串同样标识出了唯一的一个人，起到了URI的作用，所以URL是URI的子集。

URL是以描述人的位置来唯一确定一个人的。在上文我们用身份证号也可以唯一确定一个人。
对于这个在杭州的张三，我们也可以用：身份证号：123456789来标识他。
所以不论是用定位的方式还是用编号的方式，我们都可以唯一确定一个人，都是URl的一种实现，而URL就是用定位的方式实现的URI。

回到Web上，假设所有的Html文档都有唯一的编号，记作html:xxxxx，xxxxx是一串数字，
即Html文档的身份证号码，
这个能唯一标识一个Html文档，那么这个号码就是一个URI。
而URL则通过描述是哪个主机上哪个路径上的文件来唯一确定一个资源，也就是定位的方式来实现的URI。
对于现在网址我更倾向于叫它URL，毕竟它提供了资源的位置信息，
如果有一天网址通过号码来标识变成了http://741236985.html，
那感觉叫成URI更为合适，不过这样子的话还得想办法找到这个资源咯…

URI 作为更宽泛的定义是包含了 URL 的，就像三角形包含等边三角形一样。

总结一下: 资源为人 , URI是一个身份证, URL是描述人的一个地址(//…/525号寝/张三),

4.Rails 跟 REST

无

---

开篇:重要概念

RESTful 实际上是为我们请求,返回的格式做了一个规范.

一次HTTP主要分为请求跟响应两部分

请求: 地址,请求头,请求体
响应: 响应头,响应体

RESTful api 也是对这几个地方进行规范的.

// 模拟一次请求
GET http://api.baidu.com.cn/v2/meetings/files/{fileId}?page=1&limit=10

既
1. GET
2. http://api.baidu.com.cn/v2
3. /meetings/files/{fileId}
4. page=1&limit=10

现在让通过RESTful的概念跟上述部分的对照关系来进行学习

1.资源 ： 例如http://api.baidu.com.cn/v2/meetings/files/{fileId} (URL) 一个具体文件

2.集合：meetings 跟 files 都是集合,但files是file的集合

3.第三方：客户端 使用我们接口的开发者

4.表现层 :请求体跟响应体的形式 熟知的JSON格式, 资源表现形式

“资源"是一种信息实体，它可以有多种外在表现形式。我们把"资源"具体呈现出来的形式，叫做它的"表现层”（Representation）。

5.状态转化 : GET/POST/… 请求类型

基本规范 (引用地址)

1.动作

GET （SELECT）：从服务器检索特定资源，或资源列表。
POST （CREATE）：在服务器上创建一个新的资源。
PUT （UPDATE）：更新服务器上的资源，提供整个资源。
PATCH （UPDATE）：更新服务器上的资源，仅提供更改的属性。
DELETE （DELETE）：从服务器删除资源。

首先是四个半种动作：
post、delete、put/patch、get
因为put/patch只能算作一类，所以将patch归为半个。

另外还有有两个较少知名的HTTP动词：
HEAD - 检索有关资源的元数据，例如数据的哈希或上次更新时间。
OPTIONS - 检索关于客户端被允许对资源做什么的信息。

2.路径（接口命名）

路径又称"终点"（endpoint），表示API的具体网址。

在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

接口尽量使用名词，禁止使用动词，下面是一些例子。

GET         /zoos：列出所有动物园
POST        /zoos：新建一个动物园
GET         /zoos/ID：获取某个指定动物园的信息
PUT         /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH       /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE      /zoos/ID：删除某个动物园
GET         /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE      /zoos/ID/animals/ID：删除某个指定动物园的指定动物

反例：

/getAllCars
/createNewCar
/deleteAllRedCars

再比如，某个URI是/posts/show/1，其中show是动词，这个URI就设计错了，正确的写法应该是/posts/1，然后用GET方法表示show。

如果某些动作是HTTP动词表示不了的，你就应该把动作做成一种资源。比如网上汇款，从账户1向账户2汇款500元，错误的URI是：

POST /accounts/1/transfer/500/to/2

正确的写法是把动词transfer改成名词transaction，资源不能是动词，但是可以是一种服务：

POST /transaction HTTP/1.1
Host: 127.0.0.1
from=1&to=2&amount=500.00

理清资源的层次结构，比如业务针对的范围是学校，那么学校会是一级资源(/school)，老师(/school/teachers)，学生(/school/students)就是二级资源。

3. 版本（Versioning）

方法一(不推荐):将API的版本号放入URL。如：

Github采用这种做法。

https://api.example.com/v1/

方法二(推荐):将版本号放在HTTP头信息中，但不如放入URL方便和直观。

4. 过滤信息（Filtering）

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

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page_number=2&page_size=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件
参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，
GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

5. 状态码（Status Codes）

状态码范围

1xx 信息，请求收到，继续处理。范围保留用于底层HTTP的东西，你很可能永远也用不到。
2xx 成功，行为被成功地接受、理解和采纳
3xx 重定向，为了完成请求，必须进一步执行的动作
4xx 客户端错误，请求包含语法错误或者请求无法实现。范围保留用于响应客户端做出的错误，例如。他们提供不良数据或要求不存在的东西。这些请求应该是幂等的，而不是更改服务器的状态。
5xx 范围的状态码是保留给服务器端错误用的。这些错误常常是从底层的函数抛出来的，甚至
开发人员也通常没法处理，发送这类状态码的目的以确保客户端获得某种响应。
当收到5xx响应时，客户端不可能知道服务器的状态，所以这类状态码是要尽可能的避免。
服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
502 网关错误
503 Service Unavailable
504 网关超时

高级规则 (引用网址)

1. URI 中不应包含尾部正斜杠 (/)
2. 必须使用正斜杠分隔符 (/) 来表示层次关系
3. 应该使用连字符 (-) 来提高 URI 的可读性
4. 下划线 (_) 不应在 URI 中使用
5. 在 URI 路径中应该首选小写字母
6. 文件扩展名不应包含在 URI 中
7. 端点名称是单数还是复数应严格

心得示例(以后再说)

GET HTTP://IP:PORT/VERSION/SERVICE/MODULE/{RESOURCES/RESOURCE}+/{FUNCTION}+

多个资源/多个功能

资源是 大集合 包含 小集合的关系
一切都是大到小

参考

https://martinfowler.com/articles/richardsonMaturityModel.html