【RESTFUL API】- 实践
RESTFUL 是目前最流行的 API 设计规范,用于 Web 数据接口的设计。
# URL 设计
五种 HTTP 方法,对应 CRUD 操作。
- GET:读取(Read)
- POST:新建(Create)
- PUT:更新(Update)
- PATCH:更新(Update),通常是部分更新
- DELETE:删除(Delete)
下面是一些例子
- GET 域名/articles:列出所有文章(列表)
- POST 域名/articles:新建(创建)一篇文章
- GET 域名/articles/{id}:获取某个指定文章的信息
- PUT 域名/articles/{id}:更新某个指定文章的信息(提供该文章的全部信息)
- PATCH 域名/articles/{id}:更新某个指定文章信息(提供该文章部分信息)
- DELETE 域名/articles/{id}:删除某个指定文章的信息
冷知识POST和PUT的区别:
POST和PUT的区别容易被简单地误认为POST表示创建资源,PUT表示更新资源.
但实际上两者都可以用来创建或是更新数据.
单从技术上来说,他们并没有什么区别.但是在HTTP规范中POST是非等幂的,多次调用会产生不同的结果,
比如:创建一个用户,由于网络原因或是其他原因多创建了几次,那么将会有多个用户被创建.
而PUT id/456则会创建一个id为456的用户,多次调用还是会创建的结果是一样的,所以PUT是等幂的.
# 状态码
HTTP 状态码就是一个三位数,分成五个类别。
- 1xx:相关信息
- 2xx:操作成功
- 3xx:重定向
- 4xx:客户端错误
- 5xx:服务器错误
API 不需要1xx状态码,下面介绍其他四类状态码的精确含义。
2xx 状态码
200状态码表示操作成功,但是不同的方法可以返回更精确的状态码.
- GET: 200 OK
- POST: 201 Created
- PUT: 200 OK
- PATCH: 200 OK
- DELETE: 204 No Content
上面代码中,POST返回201状态码,表示生成了新的资源;DELETE返回204状态码,表示资源已经不存在。
此外,202 Accepted状态码表示服务器已经收到请求,但还未进行处理,会在未来再处理,通常用于异步操作。
3xx 状态码
API 用不到301状态码(永久重定向)和302状态码(暂时重定向,307也是这个含义),
因为它们可以由应用级别返回,浏览器会直接跳转,API 级别可以不考虑这两种情况。
API 用到的3xx状态码,主要是303 See Other,表示参考另一个 URL。
它与302和307的含义一样,也是"暂时重定向",区别在于302和307用于GET请求,而303用于POST、PUT和DELETE请求。收到303以后,浏览器不会自动跳转,而会让用户自己决定下一步怎么办。
4xx 状态码
400 Bad Request:服务器不理解客户端的请求,未做任何处理。
401 Unauthorized:用户未提供身份验证凭据,或者没有通过身份验证。
403 Forbidden:用户通过了身份验证,但是不具有访问资源所需的权限。
404 Not Found:所请求的资源不存在,或不可用。
405 Method Not Allowed:用户已经通过身份验证,但是所用的 HTTP 方法不在他的权限之内。
410 Gone:所请求的资源已从这个地址转移,不再可用。
415 Unsupported Media Type:客户端要求的返回格式不支持。比如,API 只能返回 JSON 格式,但是客户端要求返回 XML 格式。
422 Unprocessable Entity :客户端上传的附件无法处理,导致请求失败。
429 Too Many Requests:客户端的请求次数超过限额。
5xx 状态码
5xx状态码表示服务端错误。一般来说,API 不会向用户透露服务器的详细信息,所以只要两个状态码就够了。
500 Internal Server Error:客户端请求有效,服务器处理时发生了意外。
503 Service Unavailable:服务器无法处理请求,一般用于网站维护状态。
# 服务器回应
不要返回纯文本
API 返回的数据格式,不应该是纯文本,而应该是一个 JSON 对象,因为这样才能返回标准的结构化数据。
所以,服务器回应的 HTTP 头的Content-Type属性要设为application/json。
# TCP协议 (传输控制协议)
都记录到这了顺便写下tcp
TCP 协议是面向连接的通信协议,即传输数据之前,在发送端和接收端建立逻辑连接,再传输数据。
它提供了两台计算机之间的可靠无差错的数据传输。
在 TCP 连接中必须要明确客户端与服务器,由客户端向服务器发送连接请求,每次连接的创建都需要经过 “三次握手”
三次握手:TCP 协议中,在发送数据的准备阶段,客户端与服务器之间的三次交互,以保证连接的可靠
- 第一次握手:客户端向服务器发出连接请求,等待服务器确认
- 第二次握手:服务器向客户端回送一个响应,通知客户端收到连接请求
- 第三次握手:客户端再次向服务器发送确认信息,确认连接
- 完成三次握手,连接建立后,客户端和服务器可以开始数据传输,由于这种面向连接的特性。 TCP 协议可以保证传输数据的安全,所以应用十分广泛,比如:文件上传、文件下载、浏览页面