RESTful

2017-04-24 Monday     network , linux

RESTful 架构是一种互联网软件架构,它结构清晰、符合标准、易于理解、扩展方便,所以正得到越来越多网站的采用。

restful api logo

简介

REST 这个词是 Roy Thomas Fielding 在 2000 年的 博士论文 中提出,也就是他对互联网软件的架构原则,全称为 Representational State Transfer 。

他在论文中提到:”我这篇文章的写作目的,就是想在符合架构原理的前提下,理解和评估以网络为基础的应用软件的架构设计,得到一个功能强、性能好、适宜通信的架构。REST 指的是一组架构约束条件和原则。” 如果一个架构符合 REST 的约束条件和原则,我们就称它为 RESTful 架构。

要理解 RESTful 架构,最好的方法就是去理解 Representational State Transfer 这个词组所代表的具体含义,进而可以体会 REST 是一种什么样的设计。

资源, Resources

REST 中其实省略了主语 “资源”,这也就是网络上的一个事物,可以是实体,如手机号、文本、图片;也可以只是一个抽象概念,如服务。

可以用一个 URI(统一资源定位符)指向它,每种资源对应一个特定的 URI,URI 是每个资源的地址的标示符。

表现层, Representation

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

比如,文本可以用 txt 格式、HTML 格式、XML 格式、JSON 格式表现,甚至可以采用二进制格式;图片可以用 JPG 格式表现,也可以用 PNG 格式表现。

URI 只代表资源的实体,不代表它的形式,严格地说,有些网址最后的 .html 后缀名是不必要的,因为这个后缀名表示格式,属于表现层范畴,而 URI 应该只代表资源的位置;它的具体表现形式,应该在 HTTP 请求的头信息中用 AcceptContent-Type 字段指定。

状态转化, State Transfer

访问一个网站,就代表了客户端和服务器的一个互动过程,在这个过程中,就会涉及到数据和状态的变化。

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

具体来说,就是通过 HTTP 协议里面的四个表示操作方式的动词:GET (获取资源),POST (新建资源或者更新资源),PUT (更新资源),DELETE (删除资源)。

最佳实践

1. 资源命名

资源 (也就是 URI) 应该使用名词而不是动词,因为 “资源” 表示一种实体,所以应该是名词,URI 不应该有动词,动词应该放在 HTTP 协议中,而且资源一般使用复数。

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

2. 修改状态

GET 方法和查询参数不应该涉及状态改变,如果要修改状态,应该使用 PUT、POST、DELETE 方法,而不是 GET 方法来改变状态。

GET /users/711?activate GET /users/711/activate

3. HTTP 头

使用 HTTP 头声明序列化格式,在客户端和服务端,双方都要知道通讯的格式,格式在 HTTP 头部中指定。

Content-Type    请求格式
Accept          系列可接受的响应格式

4. 集合操作

可以为集合提供过滤、排序、选择和分页等功能。

----- filtering 过滤,使用唯一的查询参数进行过滤
GET /cars?color=red                    返回红色的cars
GET /cars?seats<=2                     返回小于两座位的cars集合

----- Sorting 排序,允许针对多个字段排序
GET /cars?sort=-manufactorer,+model    根据生产者降序和模型升序排列的car集合

----- Paging 分页,通过limit和offset实现分页,可以提供默认值
GET /cars?offset=10&limit=5            为了将总数发给客户端,使用订制的HTTP头 X-Total-Count

----- Field Selection 段选择,只显示资源的部分所需要字段,降低网络流量,提高API可用性
GET /cars?fields=manufacturer,model,id,color

5. 返回码

使用 HTTP 状态码处理错误,HTTP 状态码提供了 70 个出错,实际上可以只使用其中的 10 个左右。

200 – OK – 一切正常
201 – OK – 新的资源已经成功创建
204 – OK – 资源已经成功擅长

304 – Not Modified – 客户端使用缓存数据

400 – Bad Request – 请求无效,需要附加细节解释如 "JSON无效"
401 – Unauthorized – 请求需要用户验证
403 – Forbidden – 服务器已经理解了请求,但是拒绝服务或这种请求的访问是不允许的。
404 – Not found – 没有发现该资源
422 – Unprocessable Entity – 只有服务器不能处理实体时使用,比如图像不能被格式化,或者重要字段丢失。

500 – Internal Server Error – API开发者应该避免这种错误。

使用详细的错误包装错误:

{
  "errors": [
   {
    "userMessage": "Sorry, the requested resource does not exist",
    "internalMessage": "No car found in the database",
    "code": 34,
    "more info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345"
   }
  ]
}

6. 版本管理

可以在 URI 中加入版本号,也可以在 HTTP 请求头或者消息体中添加。



如果喜欢这里的文章,而且又不差钱的话,欢迎打赏个早餐 ^_^


About This Blog

Recent Posts

Categories

Related Links

  • RTEMS
    RTEMS
  • GNU
  • Linux Kernel
  • Arduino

Search


This Site was built by Jin Yang, generated with Jekyll, and hosted on GitHub Pages
©2013-2019 – Jin Yang