出于严峻听从HTTP协议举办数据再次来到公海赌船备用网址,安全性与幂等性

6.3 body采用JSON字符串。

JSON的社团分为三种:成功、败北。

一般而言,唯有重临200的时候才须要读取成功的JSON,唯有重返406和500的时候才必要读取战败的JSON,对于其余的状态码,客户端不必要服务器提供额外的信息。

对此成功的JSON,里面应该只包含一个result对象,而小败的JSON应该选拔那样的布局:

{

error: {

code: xxx,

message: "xxx",

data: {...}

}

}

挫折的JSON唯有一个error对象,包括错误码、信息及连锁数据,message应该是直接可读的音信,客户端毋需清楚暴发了何等错误,客户端只需将信息呈现出来即可。在收到406的时候,客户端只需领会发生的荒谬是由客户端造成的即可,具体是何许品种并不要求知道,将音讯平昔呈现出来,让使用的人清楚是如何即可,所以message应该是全人类可以通晓的公文。同理,收到500的时候,只需领会这些错误是服务端的题材即可,客户端也毋需知道具体的谬误类型,最多就将错误码和信息突显出来,让使用者有反馈的依照即可。

  • 绝不用小写
  • 单词间拔取下划线’_’
  • 不应用动词,资源要利用名词复数形式,如:user、rooms、tickets
  • 层级 >= 三层,则使用’?’带参数

    users/1/address/2/citys (bad) /citys?users=1&address=2;
    (good)

7 版本控制

考虑到接口有可能升级,升级的品种有两种:

  1. 增产功用接口

  2. 本来接口重返数据扩充字段

  3. 幸存接口重临数据变动现有字段格式或删除现有字段

  4. 幸存接口变更业务逻辑

  5. 除去接口

中间,前两种升级并不会影响客户端,因而毋需处理。而前边三种会招致使用旧接口的客户端无法正常干活。

一般服务端升级与客户端升级都不是同步的,客户端升级往往会掉队,由此在服务端升级后应该保留旧版本的接口继续运行一段时间,让未升级的客户端可以一连工作一段时间,同时可以上线新本子的客户端。过一段时间后再将旧版本的接口下线。

而版本控制应该是向下兼容的,即如若当前版本是1.2,如若客户端请求1.3本子的劳务,应当用当下版本提供劳动。即使没有声明请求的本子号,应当提供当前版本的劳务。

诚如景色下,客户端请求要求带版本号,但是服务端并不须要对此开展处理,除非是还要运行新旧版本的同一个接口,才要求做差别处理。

rel describe
self 资源本身,每个资源表述都一个包含此关系
edit 指向一个可以编辑当前资源的链接
delete 指向一个可以删除当前资源的链接
item 如果当前资源表示的是一个集合,则用来指向该集合中的单个资源
collection 如果当前资源包含在某个集合中,则用来指向包含该资源的集合
related 指向一个与当前资源相关的资源
first、last、prev、next 分别用来指向第一个、最后一个、上一个和下一个资源

8 实现

request

5.3 body

行使JSON字符串,具体的社团有待商定,那不属于HTTP协议的一有的,是自定义的。

此处关键放置业务相关的数目。

客户端错误

2.3 安全性

一个方式被调用1次与被调用0次是同等的,此方式就是平安的,否则就是不安全的。例如,一个方法A仅仅是读取数据,并不成立或者涂改数据,不论A方法被调用多少次,都畸形数据记录爆发其它影响,A方法是高枕无忧的。而只要有另一个方法B对数码进行删除,B方法被调用1次后,数据会被剔除(或者标识位被涂改),系统里的数额爆发了变更,那么B方法是不安全的。

分页

2.1 RESTful

REST不是一种协议,也不是一种文件格式,更不是一种开发框架。它是一文山会海的设计约束的聚众:无状态性、将超媒体作为利用状态的发动机等。REST是Representation
State
Transfer
的缩写,汉语是『表述性状态转移』,那里就提到到资源的表达与气象八个概念。

一句话来说地说,资源得以当作是服务器上囤积的所有数据,资源的抒发则是服务器对外提供的针对那几个资源的主意,使用JSON、XML等均可,一个资源得以有多种表明;资源的景色则是服务器的多寡存储状态,例如在t时刻,服务器中贮存了m条数据,那时候客户端向服务端提交了一个开立数量的伸手,服务器处理了此呼吁并创造了一条数据,那么在t+1时刻,服务器中就存储了m+1条数据,那四个时刻的资源气象就是不均等的,t时刻发生的呼吁导致了资源意况的改变。

在介绍HATEOAS在此之前,先介绍一下REST的成熟度模型

2.2 HATEOAS

Hypermedia As The Engine Of Application
State
,超媒体作为应用程序状态的发动机。那是REST差异于其余SOA风格的基本点特色。客户端与服务端进行互动的时候,完全是透过服务端动态提供的超媒体举办的。除了对超媒体的一般了解,客户端不须要精晓其余额外的知识。相反,在局地SOA接口的规划中,客户端与服务端的通讯是要事先进行预约的,例如通过文档或者接口描述语言(Interface
Description Language,
IDL)。而根据HTTP协议的REST设计里,一般选用的就是呼吁与响应的Header来显示HATEOAS原则(具体请参见:https://en.wikipedia.org/wiki/HATEOAS)。那里也隐含那样一层含义:REST应竭尽地选择HTTP标准中幸存的事物,例如Header、标准措施与状态码。

从标准的角度看,HTTP标准是一项RFC标准,世界认同;而其余自定义的SOA标准则可能是一项个人正式仍旧商店正式,最多是一项互连网草案(那对绝一大半商厦来说都不能够),而一项专业更是被广为认可接受,其促成的通用性就越强。个人正式和供销社正式都五花八门,那样对每一个业内都要参考其唇齿相依文档完毕相应的一言一动逻辑是很麻烦的。

版本控制

6.2 状态码

状态码 语义 使用场景
200 OK 正常返回消息,什么问题也没有
201 Created 创建资源成功,Header里应设置Location指向新创建的资源
202 Accepted 请求已被接收,但是处理过程较长,不能马上返回结果
304 Not Modified 没有任何修改发生
401 Unauthorized 缺乏权限,指已经登录但是缺乏请求这个资源的权限
403 Forbidden 拒绝访问,可用于未登录时拦截返回的状态码,此时Header里应设置Location为登录页面的URL
404 Not Found 不存在所请求的资源
406 Not Acceptable 请求没有被接收,参数约束校验不通过,或者其他业务类型的错误都可以返回这个状态码,response的body里应有表示错误信息的JSON实体。
409 Conflict 请求的资源有冲突,例如多次提交一样的创建请求,response的Header里应设置Location为产生冲突的资源的URL
500 Internal Server Error 服务器的非业务类错误,response的body里应有表示错误信息的JSON实体
  1. 在uri中出席版本: /v1/room/1
  2. Accept Header:Accept: v1
  3. 自定义 Header:X-Imweb-Media-Type: imweb.v1 (大家应用此方案)

5.1.1 get

赢得资源,单个参数一般写在URL上,七个参数则作为query
parameter附在URL前边,例如:

  • 单个参数:/user/123, 表示id为123的user

  • 五个参数:/user?name=tom&phone=13787890987&gender=male

get方法应为幂等的,并且不对数据记录发生潜移默化。对于汉字与特殊字符,应该举行urlencode。

三种方案:

5.1.3 put

更新资源,对现有资源开展改动,请求的headers与post一样,参数也是。此措施应该是幂等的。

response

5.1.2 post

创立资源,请求的headers里安装Content-typeapplication/json,参数为json类型。

依照约定,在创建成功将来,重返的状态码应该是201(Created),并且在response的Header里设置Location为新成立的资源的URL,例如,创建了一个新的user,该user创立后id为888,那么Header里应该安装Location/users/888,当然,那应该是一个完全的URL,那里只是给出了一个相对路径的URI以作为讲明。重临了这个数量后,客户端可以自定义后续行为,或者查看创立后的user,或者刷新当前的user列表,那一个表现服务端并不爱戴。

一旦重新提交了相同的多少,第四次应该回到201,以后则应再次来到409(Conflict),并且在response的Header里设置Location指向已经存在的资源,表明争执的起源。

理解RESTful架构:http://www.ruanyifeng.com/blog/2011/09/restful.html

5 请求

response

1.2 为啥使用REST

目标是为了服务端与客户端的解耦。SOA仅仅是从结构中将前后端分离,不过其实数据逻辑仍旧尚未落实解耦,服务端接口升级往往会潜移默化客户端,两者的行为须要严厉约定。而REST选拔HTTP协议进行预定,客户端仅仅必要遵从HTTP协议来通晓服务端重返的数据,固然与作业有关的数据结构依然须要预订,然而那诚然越来越解耦了服务端与客户端。

其它,由于严苛听从HTTP协议举行数量重返,对于平安的接口,可以在重回的Header里设置缓存策略(接口安全性的概念在下文仲解释)。

request

1 概述

自定义Media-Type参考资料github

1.1 撰写目的

正文用于定义一种统一的RESTful接口设计方案,希望保有参考价值。本文所讲述的方案相比较高校派,在上一家公司提议没有被采用,在所通晓到的星星点点的几何家声称利用了RESTful风格的商家里,发现他们也偏离甚远。当然,他们那样做是有理由的,我也精通,那只是接纳难点。那篇小说其实是旧文了,二〇一六年岁暮就早已写好,不过一贯躺在统计机的硬盘里,不想白费了当时的功夫,由此在此公开。

  • limit:再次回到记录数据
  • offset:再次回到记录的开始地方

3 URL命名

URL用于标识资源,由此URL应该以名词进行命名,例如/users,
/users/children等。

诚如URL会内嵌参数,例如要博取id为313的user的音讯,那么URL应该为/users/313,后面的user选拔复数,若是要列出其持有后代,则URL应为/users/313/children,children为复数方式,若是要博得其id为499的后生,则URL应为/users/313/children/499

/users?limit=10&offset=10

2 关键概念

强烈一些第一的定义是很首要的,纵然RESTful风格的API设计方案并没有统一的专业,可是仍旧要求符合自然的条件举办统筹,否则就不可能称之为RESTful风格的API。因为不少人并没有对REST进行丰硕的询问就声称自己的API是RESTful风格的API,以至于RESTful的发起人Fielding硕士本人不可以忍受,在二〇〇八年为此特意写了一篇博客『REST
APIs must be
hypertext-driven
』,hypertext-driven与HATEOAS是同一个概念的两样表明,在下文仲举行阐释。

HATEOAS

5.2 Header

Content-type应设为application/json。

除此以外应设置一个version,指明所使用的接口版本。那不属于HTTP协议中的一有些,是自定义的,出于版本控制的勘查,具体见第七章。

过滤

4 新闻实体

音信实体,就是请求和响应音讯中的entity-body(也号称body),信息实体选拔JSON字符串格式。

GET

6 响应

http://novoland.github.io/%E8%AE%BE%E8%AE%A1/2015/08/17/Restful%20API%20%E7%9A%84%E8%AE%BE%E8%AE%A1%E8%A7%84%E8%8C%83.html

1.3 文档结构

第二片段将解说关于RESTful的几何个基本点的定义,明确第二部分阐释的多少个概念有利于统筹、已毕优雅规范的接口。

其三片段就URL命名的题材举行约定。

第四有些对音信实体进行预定。

第五片段对『向RESTful接口发起呼吁』进行演讲,约定要完结的法子,约定请求的尾部和body的格式。

第六片段对接口的响应格式进行预定,包蕴响应新闻的底部、状态码、JSON实体。

第七局地对版本控制的难题展开预定。

第八部分对RESTful接口的兑现提议了落到实处工具的提议。

Request

2.4 幂等性

一个措施被同一地调用1次与被调用很多次是如出一辙的,即一律的输入会拿走平等的出口,此方法就是幂等的,否则就不是幂等的。

2.3节中A方法与B方法都是幂等的,一个安然无恙的法子肯定是幂等的,一个幂等的办法不肯定是安全的。

若果一个方法C对某个全局计数器执行自增操作并写入数据库,每回调用C方法都会对系统数据发生震慑,那么C方法就不是幂等的。

权力用户

5.1.4 delete

除去资源。此方法应是幂等的。

  • 添加_method参数

    /users/1?_method=put&name=111
    
  • 添加X-HTTP-Method-Override请求头 (大家使用那种办法)

    X-HTTP-Method-Override: PUT
    

6.1 Header

依照响应的状态码不同,相应地安装底部,具体见下一节。

然而在我所通晓的商店里,做法都是联合再次来到200,然后在回到的JSON字符串里安装音信码。我是不可能明了的。据一位前端同学说,前端代码接收到了请求将来,不便民获取Http状态码。其实自己也写过前端,不深刻,不过一些骨干的知识或者有些,我认为那并简单成功,估算是他的代码封装的时候没有设想到这点,现在要改相比麻烦,所以不想大动干戈、伤筋动骨。

  • 安全性:任意很多次对同样资源操作,都不会导致资源的情景变化
  • 幂等性:任意次对同一资源操作,对资源的改变是相同的
  • Method 安全性 幂等性
    GET
    POST × ×
    PUT ×
    PATCH ×
    DELETE ×

5.1 方法

利用HTTP标准定义的伸手方法。

http://www.coderli.com/translate-restful-standard-resolved/

8.1 Spring HATEOAS

Spring HATEOAS可以很有益于地与Spring
MVC结合来支付RESTful接口。具体参照其文档:

http://docs.spring.io/spring-hateoas/docs/0.20.0.RELEASE/reference/html/\#fundamentals.jaxb-json

原文链接:
https://bungder.github.io/2017/07/24/REST/

自己的技巧博客:
https://bungder.github.io


缘何简书的马克Down不帮助表格语法……

安全性与幂等性

RESTful API
设计指南:http://www.ruanyifeng.com/blog/2014/05/restful_api.html

request请求,查询user,每页展现10条,从第10条起首突显(第二页)

{
        data: {
            xxx
        },
        meta: {
            _link: [
                {rel: 'self', href: 'xxx/orders/1'},
                {rel: 'related', href: 'xxx/orders/1/payment', title: 'pay the order'}
            ]
        }
}

此用户所有修改与删除订单的权位,因而回到了3个资源

?type=1&state=closed

_link回到八个资源

{
        data: {
            xxxx
        },
        meta: {
            _link: [
                {rel: 'self', href: 'xxx/users?limit=10&offset=10'},
                {rel: 'first', href: 'xxx/users?limit=10&offset=0', title: 'first page'},
                {rel: 'last', href: 'xxx/users?limit=10&offset=50', title: 'last page'},
                {rel: 'prev', href: 'xxx/users?limit=10&offset=0', title: 'prev page'},
                {rel: 'next', href: 'xxx/users?limit=10&offset=20', title: 'next page'}
            ]
        }    
}

单参数多字段

http://imweb.io/topic/5707561f06f2400432c139a5(以下内容转自此篇文章)

  • GET:查询资源
  • POST:创造资源
  • PUT/PATCH

    • PUT:全量更新资源(提供改变后的完好资源)
    • PATCH:局地更新资源(仅提供改变的习性)
  • DELETE:删除资源

上述是大规模的状态码,完整的情景码列表在那状态码

Code Method Describe
200 ALL 请求成功并返回实体资源
201 POST 创建资源成功

HATEOAS总结

Method

/orders/1

https://www.zhihu.com/question/28557115

GitHub标准RESTful API:https://api.github.com/

/orders/1

response

兼容

  • rel: ‘self’,资源本身
  • rel: ‘edit’,此用户可修改该资源
  • rel: ‘delete’,此用户可去除该资源

_link返回了5个资源

URI

http://blog.csdn.net/u013731455/article/details/56278168

由上述例子可以看出_link哪怕以Hyperlink表述资源与资源之间的关系,这种办法使客户端与服务端能很好的分开开来,只要接口的定义不变,客户端与服务端就可以独立的费用和嬗变。

权限相关

/users/1?fields=name,age,city
  • +升序,如?sort=+create_time,根据id升序
  • -降序,如?sort=-create_time,根据id降序
?limit=10&offset=10
CODE METHOD DESCRIBE
500 ALL 服务器未知错误
  • 非id的参数使用’?’形式传输

    /users/1?state=closed
    

    ##### POST、PATCH、PUT、DELETE

  • 非id的参数使用body传输,并且应该encode

在介绍 HATEOAS 在此之前,先介绍一下 Richardson 提议的 REST
成熟度模型。该模型把 REST 服务按照成熟度划分成 4 个层次:

  • 首先个层次(Level 0)的 Web 服务只是使用 HTTP
    作为传输格局,实际上只是长途方法调用(RPC)的一种具体形式。
  • 第三个层次(Level 1)的 Web
    服务引入了资源的概念。每个资源有相应的标识符和表明。
  • 其五个层次(Level 2)的 Web 服务使用分化的 HTTP
    方法来开展区其他操作,并且动用 HTTP 状态码来表示分化的结果。如
    HTTP GET 方法来获取资源,HTTP DELETE 方法来删除资源。
  • 第一个层次(Level 3)的 Web 服务使用
    HATEOAS。在资源的表明中带有了链接音信。客户端可以根据链接来发现可以实施的动作。

很多客户只扶助GET/POST请求,一般有二种方式模拟PUT等请求

服务器错误

例子

简述

{
        data: {
            xxx
        },
        meta: {
            _link: [
                {rel: 'self', href: 'xxx/orders/1'},
                {rel: 'edit', href: 'xxx/orders/1', title: 'edit the order'},
                {rel: 'delete', href: 'xxx/orders/1', title: 'delete the order'}
            ]
        }
}
  • rel: ‘self’,资源本身
  • rel:
    ‘related’,与当前资源相关的资源,/order/1/payment用户可以使用此资源举行支付
  • rel: ‘self’,资源本身
  • rel: ‘first’,第一页资源
  • rel: ‘last’,最后一页资源
  • rel: ‘prev’,上一页资源
  • rel: ‘next’,下一页资源

URI规范

普通用户

评释:其实没有相对的正儿八经,达到90%即可。


排序

Code Method Describe
400 ALL 一般是参数错误
401 ALL 一般用户验证失败(用户名、密码错误等)
403 ALL 一般用户权限校验失败
404 ALL 资源不存在(github在权限校验失败的情况下也会返回404,为了防止一些私有接口泄露出去)
422 ALL 一般是必要字段缺失或参数格式化问题

常用rel

参数

如用户查询一个订单

状态码

HATEOAS(Hypermedia as the engine of application state)是 REST
架构风格中最复杂的牢笼,也是打造成熟 REST
服务的着力。它的重大在于客户端和服务器之间的解耦。

Method

课程收集:

成功

http://blog.csdn.net/yue7603835/article/details/52536497

分页

使用, 分隔,如

相关文章