依据财富,基于财富

本文首要读者

本文首要读者

引言

引言

REST是什么

REST是什么

  联合接口

  统1接口

    基于能源

    依据能源

    经过特色来操作财富

    因此特色来操作财富

    自描述的消息

    自描述的消息

    超媒体即选用状态引擎(HATEOAS)

    超媒体即采纳状态引擎(HATEOAS)

  无状态

  无状态

  可缓存

  可缓存

  C-S架构

  C-S架构

  分段系统

  分层系统

  按需编码(可选)

  按需编码(可选)

REST火速提醒

REST火速提醒

  动用HTTP动词表示一些意思

  使用HTTP动词表示1些意思

  创造的能源名

  合理的财富名

  XML和JSON

  XML和JSON

  创设适当粒度的财富

  创建适当粒度的财富

  考虑连通性

  思考连通性

定义

定义

  幂等性

  幂等性

  安全

  安全

HTTP动词

HTTP动词

  GET

  GET

  PUT

  PUT

  POST

  POST

  PUT和POST的开创相比较

  PUT和POST的创制比较

  DELETE

  DELETE

能源命名

能源命名

  资源URI示例

  资源URI示例

  财富命名的反例

  能源命名的反例

  复数

  复数

回去表征

回到表征

  财富通过链接的可发现性(HATEOAS续)

  能源通过链接的可发现性(HATEOAS续)

    小小化链接推荐

    小小的化链接推荐

    链接格式

    链接格式

  打包响应

  卷入响应

  拍卖跨域难点

  拍卖跨域难题

    支持CORS

    支持CORS

    支持JSONP

    支持JSONP

询问,过滤和分页

询问,过滤和分页

  结果限制

  结果限制

    用范围标志进行限制

    用范围标志进行界定

    用字符串查询参数举办限定

    用字符串查询参数进行限制

    遵照范围的响应

    基于范围的响应

  分页

  分页

  结果的过滤和排序

  结果的过滤和排序

    过滤

    过滤

    排序

    排序

劳动版本管理

劳务版本管理

  透过内容协商辅助版本管理

  通过剧情协商补助版本管理

  当未有点名版本时,再次回到什么版本?

  当未有点名版本时,重返什么版本?

  请求不帮忙的版本

  恳请不协理的版本

  如哪天候应该成立二个新本子?

  什么样时候应该创立一个新本子?

    破坏性的修改

    破坏性的修改

    非破坏性的退换

    非破坏性的退换

  版本调整应在怎么等第出现?

  版本调整应在如何等级出现?

  行使Content-Location来抓好响应

  动用Content-Location来增长响应

  带有Content-Type的链接

  带有Content-Type的链接

  寻找协理的本子

  找寻帮衬的版本

    笔者应该同时帮忙多少个本子?

    自己应当同时帮助多少个版本?

    弃用

    弃用

    本身何以告知客户端被弃用的财富?

    自个儿怎么样告知客户端被弃用的财富?

日子/时间处理

日期/时间处理

  Body内容中的日期/时间连串化

  Body内容中的日期/时间系列化

  HTTP
Headers中的日期/时间系列化

  HTTP
Headers中的日期/时间系列化

护卫服务的安全

有限帮忙服务的辽阳

  身份验证

  身份验证

  传输安全

  传输安全

  授权

  授权

  应用程序安全

  应用程序安全

缓存和可伸缩性

缓存和可伸缩性

  ETag Header

  ETag Header

HTTP状态码(前10)

HTTP状态码(前10)

叠加能源

外加能源

  书籍

  书籍

  网站

  网站

 

 

本文首要读者

  该最棒实行文书档案适用于对RESTful
Web服务感兴趣的开辟人士,该服务为跨八个劳务的零件提供了较高的可靠性和壹致性。依照本文的点拨,可神速、广泛、公开地为内外部客户利用。

  本文中的教导标准壹致适用于工程师们,他们期望利用那么些依据最棒施行标准开荒的劳务。即使他们进一步关怀缓存、代理规则、监听及平安等有关地点,可是该文书档案能作为1份包蕴全数品类服务的总指南。

  其它,通过从这个指引原则,管理职员了然到创建公共的、提供高牢固性的劳动所需开支的用力,他们也可从中收益。

 

正文重要读者

  该最棒实行文书档案适用于对RESTful
Web服务感兴趣的开采人士,该服务为跨七个服务的零部件提供了较高的可信赖性和壹致性。按照本文的点拨,可迅速、广泛、公开地为内外部客户使用。

  本文中的指引原则一致适用于工程师们,他们盼望选用这个依据最棒实施标准开采的服务。即使她们越来越保护缓存、代理规则、监听及安全等连锁方面,不过该文书档案能作为一份包罗全数系列服务的总指南。

  其余,通过从这几个辅导规范,管理人士理解到创设公共的、提供高稳固的劳重力管理服务所需费用的努力,他们也可从中获益。

 

引言

  到现在已有雅量关于RESTful
Web服务至上施行的相干材质(详见本文最终的有关文献部分)。由于撰文的大运不1,很多质感中的内容是争辨的。其余,想要通过翻看文献来理解那种服务的开荒进取是不太可取的。为了打探RESTful这一定义,至少须求查阅3到5本有关文献,而本文将能够帮你增加速度这一历程——甩掉多余的钻探,最大化地提炼出REST的特级施行和规范。

  与其说REST是1套标准,REST更像是1种规格的集合。除了八个基本点的标准外就一贯不其余的正经了。实际上,尽管有所谓的“最好实践”和正式,但这几个东西都和宗教斗争同样,在频频地演化。

  本文围绕REST的大面积难点建议了见识和仿美食指南式的议论,并通过介绍部分轻松的背景知识对创立真实情况下的预生产条件中一样的REST服务提供文化。本文收罗了来自别的路子的消息,经历过二次次的败诉后不断革新。

  但对此REST形式是不是分明比SOAP好用仍有较大争议(反之亦然),只怕在少数意况下仍急需创建SOAP服务。本文在聊到SOAP时并未有花较大篇幅来商讨它的相对优点。相反由于技巧和行当在不断进步,大家将延续持之以恒我们的借使–REST是即时规划web服务的极品办法。

  第2局地概述REST的意思、设计准则和它的奇异之处。第三部分点数了部分小贴士来纪念REST的劳动意见。之后的有的则会更深切地为web服务创造人员提供①些细节的支持和座谈,来落实三个可以领会议及展览示在生育条件中的高素质REST服务。

 

引言

  于今已有大气有关RESTful
Web服务至上实施的连带资料(详见本文最后的连锁文献部分)。由于撰文的年月各异,许多素材中的内容是冲突的。别的,想要通过查阅文献来询问那种劳动的上进是不太可取的。为了明白RESTful这一概念,至少供给查阅三到伍本有关文献,而本文将能够帮您加速这一进程——放任多余的座谈,最大化地提炼出REST的拔尖实施和正规。

  与其说REST是1套标准,REST更像是1种标准的聚集。除了三个主要的规范外就从未有过其他的专业了。实际上,固然有所谓的“最好实施”和行业内部,但这么些事物都和宗教斗争同样,在不停地衍生和变化。

  本文围绕REST的宽泛难题提议了思想和仿美食做法式的座谈,并透过介绍部分简短的背景知识对创建真实境况下的预生产环境中同样的REST服务提供文化。本文搜罗了来自此外门路的音信,经历过二遍次的挫败后不断立异。

  但对于REST情势是或不是料定比SOAP好用仍有较大争议(反之亦然),或许在好几情状下仍须求创立SOAP服务。本文在聊到SOAP时并未有花较大篇幅来钻探它的绝对优点。相反由于手艺和行业在不断提高,我们将承继百折不挠大家的比方–REST是及时设计web服务的特等方式。

  第一有个别概述REST的含义、设计准则和它的超常规之处。第一有的列举了壹部分小贴士来回想REST的服务意见。之后的有个别则会更透顶地为web服务创造职员提供部分细节的援救和议论,来兑现贰个力所能及领悟展现在生产环境中的高素质REST服务。

 

REST是什么?

  REST架构形式讲述了各种设计准则。这一个用于架构的布置准则,最早是由罗伊Fielding在他的大学生随想中建议并定义了RESTful风格。(详见http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

  八个规划准则分别是:

  • 统壹接口
  • 无状态
  • 可缓冲
  • C-S架构
  • 分层系统
  • 按需编码

  以下是那一个陈设准则的详实谈论:

REST是什么?

  REST框架结构情势讲述了多种设计准则。这么些用于架构的规划准则,最早是由RoyFielding在他的硕士散文中提议并定义了RESTful风格。(详见http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

  多个统一筹划准则分别是:

  • 统一接口
  • 无状态
  • 可缓冲
  • C-S架构
  • 支行系统
  • 按需编码

  以下是这么些安顿准则的详实切磋:

合并接口

  统1接口准则定义了客户端和服务端之间的接口,简化和分手了架构,这样壹来每一个部分都可单独演变。以下是接口统1的三个规范:

合并接口

  统1接口准则定义了客户端和服务端之间的接口,简化和分手了架构,那样1来每种部分都可独自衍变。以下是接口统一的多个条件:

  基于财富

  不一致财富须要用U牧马人I来唯1标志。重回给客户端的特色和能源自个儿在概念上有所差别,例如服务端不会从来传送一个数据库财富,可是,1些HTML、XML或JSON数据可见展现部分数据库记录,如用丹麦语来表述仍然用UTF-八编码则要依照请求和服务器实现的底细来调整。

  基于财富

  不一致资源必要用U哈弗I来唯1标记。再次来到给客户端的特色和能源自身在概念上有所不相同,例如服务端不会一贯传送2个数据库财富,然则,壹些HTML、XML或JSON数据可见体现部分数据库记录,如用保加利亚语来发挥照旧用UTF-八编码则要根据请求和服务器达成的底细来决定。

  通过特色来操作财富

  当客户端收到包蕴元数据的资源的天性时,在有权力的地方下,客户端已调整的够用的新闻,能够对服务端的能源拓展删改。

  通过特征来操作财富

  当客户端收到包涵元数据的财富的风味时,在有权力的处境下,客户端已驾驭的足足的新闻,能够对服务端的能源拓展删改。

  自描述的音讯

  每条音讯都富含丰硕的数据用于确认音讯该怎么处理。例如要由互连网媒体类型(已知的如MIME类型)来承认需调用哪个解析器。响应一样也标记了它们的缓存技能。

  自描述的新闻

  每条新闻都带有丰裕的数码用于确认音讯该怎样处理。例如要由网络媒体类型(已知的如MIME类型)来承认需调用哪个解析器。响应同样也标记了它们的缓存技能。

  超媒体即接纳状态引擎(HATEOAS)

  客户端通过body内容、查询串参数、请求头和UPRADOI(财富名称)来传送状态。服务端通过body内容,响应码和响应头传送状态给客户端。那项技巧被称呼超媒体(或超文本链接)。

  除了上述剧情外,HATEOS也代表,要求的时候链接也可被含有在再次来到的body(或头部)中,以提供U奥迪Q5I来寻找对象自小编或涉嫌对象。下文将对此开始展览更详实的阐发。

  统壹接口是各类REST服务布置时的不能缺少准则。

  超媒体即选取状态引擎(HATEOAS)

  客户端通过body内容、查询串参数、请求头和UBMWX三I(财富名称)来传送状态。服务端通过body内容,响应码和响应头传送状态给客户端。那项才干被叫做超媒体(或超文本链接)。

  除了上述剧情外,HATEOS也意味,供给的时候链接也可被含有在回去的body(或底部)中,以提供UEnclaveI来搜寻对象自笔者或涉及对象。下文将对此张开更详细的解说。

  统1接口是种种REST服务规划时的必需准则。

无状态

  正如REST是REpresentational State
Transfer的缩写,无状态很关键。本质上,那标识了拍卖请求所需的情景已经包罗在呼吁作者里,也有十分的大可能率是U库罗德I的1有些、查询串参数、body或底部。UEscortI能够唯一标志每种能源,body中也蕴藏了能源的转态(或转态更改情状)。之后,服务器将展开始拍戏卖,将有关的气象或能源通过尾部、状态和响应body传递给客户端。

  从事大家那1行业的半数以上人都习惯使用容器来编制程序,容器中有2个“会话”的概念,用于在七个HTTP请求下保持状态。在REST中,如若要在多个请求下维持用户景况,客户端必须总结客户端的装有音信来形成请求,供给时再也发送请求。自从服务端不必要保持、更新或传递会话状态后,无状态性得到了越来越大的延展。其它,负载均衡器无需忧虑和无状态系统之间的对话。

  所以状态和财富间有如何差距?服务器对于状态,也许说是应用状态,所关切的点是在当前对话或请求中要到位请求所需的数据。而能源,可能说是财富气象,则是概念了能源特色的数目,例如存储在数据库中的数据。不问可见,应用状态是是随着客户端和伸手的改换而更换的数额。相反,财富情形对于发出请求的客户端的话是不改变的。

  在互联网利用的某一一定岗位上摆放二个回去按键,是因为它希望你能按一定的相继来操作吗?其实是因为它违反了无状态的标准。有繁多不信守无状态原则的案例,例如叁-Legged
OAuth,API调用速度限制等。但如故要硬着头皮确定保障服务器中不必要在三个请求下保持利用状态。

无状态

  正如REST是REpresentational State
Transfer的缩写,无状态很重大。本质上,那注明了处理请求所需的情景已经蕴涵在呼吁笔者里,也有希望是U中华VI的一有个别、查询串参数、body或尾部。ULANDI能够唯一标记每一个能源,body中也蕴涵了能源的转态(或转态改换意况)。之后,服务器将拓展处理,将有关的图景或能源通过底部、状态和响应body传递给客户端。

  从事大家那1行当的诸多人都习惯使用容器来编制程序,容器中有贰个“会话”的概念,用于在五个HTTP请求下保持状态。在REST中,如若要在三个请求下保持用户情状,客户端必须归纳客户端的持有信息来成功请求,须求时再也发送请求。自从服务端不须求保障、更新或传递会话状态后,无状态性获得了越来越大的延展。其余,负载均衡器无需顾忌和无状态系统里面包车型地铁对话。

  所以状态和财富间有哪些分歧?服务器对于状态,只怕说是应用状态,所关注的点是在此时此刻对话或请求中要做到请求所需的多少。而财富,或然说是财富情状,则是概念了能源特色的多寡,例如存款和储蓄在数据库中的数据。综上可得,应用状态是是随着客户端和伸手的变动而更换的数目。相反,财富情况对于发出请求的客户端的话是不改变的。

  在网络使用的某一一定岗位上摆放三个重回按键,是因为它愿意你能按自然的逐条来操作吗?其实是因为它违反了无状态的规则。有无数不服从无状态原则的案例,例如三-Legged
OAuth,API调用速度限制等。但照旧要尽量有限支持服务器中不供给在三个请求下维持利用状态。

可缓存

  在万维网上,客户端能够缓存页面包车型大巴响应内容。由此响应都应隐式或显式的定义为可缓存的,若不足缓存则要幸免客户端在频仍请求后用旧数据或脏数据来响应。管理妥贴的缓存会部分地或完全地除了客户端和服务端之间的交互,进一步立异质量和延展性。

可缓存

  在万维网上,客户端能够缓存页面包车型地铁响应内容。因此响应都应隐式或显式的概念为可缓存的,若不足缓存则要制止客户端在数十四回呼吁后用旧数据或脏数据来响应。管理伏贴的缓存会部分地或完全地除了客户端和服务端之间的相互,进一步改革品质和延展性。

C-S架构

  统一接口使得客户端和服务端相互分开。关怀分离意味什么?打个假如,客户端不须要仓库储存数据,数据都留在服务端内部,那样使得客户端代码的可移植性获得了升高;而服务端不需求思索用户接口和用户情形,那样一来服务端将越加简便易行易拓展。只要接口不改造,服务端和客户端能够独自地进行研发和替换。

C-S架构

  统一接口使得客户端和服务端互相分开。关心分离意味什么?打个比方,客户端不供给仓储数据,数据都留在服务端内部,那样使得客户端代码的可移植性获得了升迁;而服务端不需求考虑用户接口和用户意况,那样一来服务端将进一步简明易拓展。只要接口不转移,服务端和客户端能够独自地拓展研究开发和替换。

分段系统

  客户端平日无法申明自个儿是一贯或然直接与端服务器举行连接。中介服务器能够经过启用负载均衡或提供共享缓存来提高系统的延展性。分层时1致要思虑安全攻略。

支行系统

  客户端平常不能表明本人是直接只怕直接与端服务器实行连接。中介服务器能够因而启用负载均衡或提供共享缓存来提高系统的延展性。分层时一样要怀想安全战略。

按需编码(可选)

  服务端通过传输可施行逻辑给客户端,从而为其权且拓展和定制功效。相关的例证有编写翻译组件Java
applets和客户端脚本JavaScript。

  遵守上述原则,与REST架构风格保持1致,能让各样分布式超媒体系统全数梦想的自然属性,比如高品质,延展性,简洁,可变性,可视化,可移植性和可信赖性。

  提示:REST架构中的筹划准则中,只有按需编码为可选项。假诺有个别服务违反了别样随意一项准则,严酷意思上不能够称之为RESTful风格。

 

按需编码(可选)

  服务端通过传输可实行逻辑给客户端,从而为其权且拓展和定制功用。相关的例证有编写翻译组件Java
applets和客户端脚本JavaScript。

  遵循上述条件,与REST架构风格保持壹致,能让种种分布式超媒连串统有着梦想的自然属性,比如高质量,延展性,简洁,可变性,可视化,可移植性和可靠性。

  提醒:REST架构中的统一筹划准则中,唯有按需编码为可选项。假设某些服务违反了其它随意一项准则,严苛意思上无法称之为RESTful风格。

 

REST火速提示

  (根据地点提到的两个标准化)不管在技巧上是或不是RESTful的,那里有一部分像样REST概念的提出。服从它们,能够兑现更加好、更有效的劳动:

REST快速提醒

  (遵照上边提到的四个规范)不管在技艺上是否RESTful的,那里有一部分接近REST概念的提出。听从它们,可以兑现越来越好、更有效的服务:

选用HTTP动词表示一些意思

  任何API的使用者能够发送GET、POST、PUT和DELETE请求,它们异常的大程度鲜明了所给请求的目标。同时,GET请求不可能改换任何秘密的能源数量。衡量和追踪仍恐怕发生,但只会更新数据而不会更新由UEnclaveI标志的能源数量。

应用HTTP动词表示1些意义

  任何API的使用者能够发送GET、POST、PUT和DELETE请求,它们异常的大程度鲜明了所给请求的目标。同时,GET请求无法改动任何秘密的能源数量。度量和追踪仍恐怕产生,但只会更新数据而不会更新由UBMWX3I标记的能源数量。

成立的财富名

  合理的能源名称只怕路线(如/posts/23而不是/api?type=posts&id=2三)能够更明了二个呼吁的目标。使用ULX570L查询串来过滤数据是很好的秘技,但不应当用于固定能源名称。

  适当的财富名叫服务端请求提供上下文,扩大服务端API的可明白性。通过U兰德索罗德I名称分层地查看财富,能够给使用者提供3个友好的、轻便掌握的财富层次,以在他们的应用程序上运用。财富名称应当是名词,幸免为动词。使用HTTP方法来钦命请求的动作部分,能让事情更是的显然。

理所当然的资源名

  合理的财富名称恐怕路线(如/posts/二三而不是/api?type=posts&id=二叁)能够更显眼五个伸手的指标。使用U猎豹CS陆L查询串来过滤数据是很好的不2秘技,但不应该用于固定财富名称。

  适当的财富名字为服务端请求提供上下文,扩张服务端API的可驾驭性。通过UCRUISERI名称分层地查看财富,能够给使用者提供2个要好的、轻松明白的能源层次,以在他们的应用程序上应用。能源名称应当是名词,防止为动词。使用HTTP方法来钦赐请求的动作部分,能让事情更是的明显。

XML和JSON

  提出暗许支持json,并且,除非开销很惊人,不然就同时支持json和xml。在神奇图景下,让使用者仅透过退换扩充名.xml和.json来切换类型。其它,对于支撑ajax风格的用户分界面,三个被卷入的响应是10分有赞助的。提供1个棉被服装进的响应,在暗许的或然有单独扩充名的图景下,例如:.wjson和.wxml,表明客户端请求三个被卷入的json或xml响应(请参见下边包车型客车包裹响应)。

  “标准”中对json的须要很少。并且这一个供给只是语法性质的,非亲非故内容格式和布局。换句话说,REST服务端调用的json响应是研究的一片段——在专业中尚无相关描述。更多关于json数据格式可以在http://www.json.org/上找到。

  关于REST服务中xml的施用,xml的科班和预订除了利用语法正确的价签和文本外未有别的的法力。特别地,命名空间不是也不该是被采纳在REST服务端的前后文中。xml的回来更近乎于json——轻便、轻易阅读,未有形式和命名空间的细节表现——仅仅是数码和链接。倘使它比那更扑朔迷离的话,参看本节的第叁段——使用xml的基金是惊心动魄的。鉴于我们的经历,很少有人使用xml作为响应。在它被全然淘汰此前,那是终极3个可被一定的地方。

XML和JSON

  提出暗中认可扶助json,并且,除非费用很振憾,不然就同时支持json和xml。在地道图景下,让使用者仅透过转移扩大名.xml和.json来切换类型。其余,对于支撑ajax风格的用户分界面,一个被打包的响应是可怜有扶助的。提供多少个被包裹的响应,在暗许的要么有独立扩张名的情事下,例如:.wjson和.wxml,注解客户端请求三个棉被服装进的json或xml响应(请参见上边包车型地铁卷入响应)。

  “标准”中对json的须要很少。并且那一个需要只是语法性质的,非亲非故内容格式和布局。换句话说,REST服务端调用的json响应是研讨的1部分——在标准中并未有相关描述。越多关于json数据格式能够在http://www.json.org/上找到。

  关于REST服务中xml的利用,xml的专业和平条约定除了利用语法正确的价签和文本外没有别的的效益。尤其地,命名空间不是也不该是被选用在REST服务端的内外文中。xml的回来更就如于json——轻便、轻松阅读,未有方式和命名空间的细节表现——仅仅是数额和链接。假设它比那更扑朔迷离的话,参看本节的第二段——使用xml的本金是担惊受怕的。鉴于大家的经历,很少有人使用xml作为响应。在它被全然淘汰从前,那是终极1个可被一定的地点。

创造适当粒度的能源

  一同始,系统中模仿底层应用程序域或数据库架构的API更便于被成立。最终,你会愿意将这个劳务都整合到手拉手——利用多项底层财富缩小通信量。在创立独立的资源之后再创设越来越大粒度的能源,比从越来越大的合集中创造较大粒度的财富越来越轻便一些。从局地小的容易定义的财富初步,成立CRUD(增加和删除查改)成效,能够使能源的创立变得更便于。随后,你能够创设那么些依照用例和压缩通讯量的财富。

创建适当粒度的能源

  一齐先,系统中效仿底层应用程序域或数据库架构的API更便于被创制。最终,你会希望将这个劳动都构成到一块儿——利用多项底层能源减弱通讯量。在开创独立的财富之后再成立更加大粒度的财富,比从越来越大的合集中制造较大粒度的能源越是便于1些。从1些小的轻松定义的能源开首,创设CRUD(增加和删除查改)成效,能够使财富的开创变得更易于。随后,你可以成立这么些依据用例和缩短通讯量的财富。

设想连通性

  REST的原理之壹就是连通性——通过超媒体链接实现。当在响应中回到链接时,api变的更具有自描述性,而在未曾它们时服务端照旧可用。至少,接口本身可感到客户端提供哪些寻找数据的参照。其余,在经过POST方法创立财富时,还是能运用头地点包蕴3个链接。对于响应中补助分页的集聚,”first”、
“last”、”next”、和”prev”链接至少是格外有效的。

 

思虑连通性

  REST的规律之1正是连通性——通过超媒体链接完成。当在响应中回到链接时,api变的更有着自描述性,而在未曾它们时服务端依旧可用。至少,接口本人可以为客户端提供什么找出数据的参考。其它,在通过POST方法创制能源时,还足以选拔头地点包含一个链接。对于响应中扶助分页的汇合,”first”、
“last”、”next”、和”prev”链接至少是尤其实惠的。

 

定义

定义

幂等性

  不要从字面意思来领悟什么是幂等性,恰恰相反,那与某个职能紊乱的园地非亲非故。上面是出自维基百科的解说:

在Computer科学中,术语幂等用于更宏观地讲述二个操作,3回或频仍实行该操作产生的结果是均等的。依据使用的上下文,那或然有两样的意思。例如,在章程依旧子例程调用具备副功效的事态下,意味着在首先调用之后被修改的情形也维持不改变。

  从REST服务端的角度来看,由于操作(或服务端调用)是幂等的,客户端能够用重新的调用而发出同样的结果——在编制程序语言中操作像是二个”setter”(设置)方法。换句话说,就是运用多个壹律的乞求与利用单个请求效果同样。注意,当幂等操作在服务器上产生同样的结果(副成效),响应自己可能是例外的(例如在八个请求之间,财富的场所也许会改变)。

  PUT和DELETE方法被定义为是幂等的。查看http请求中delete动词的警戒新闻,可以参见下文的DELETE部分。GET、HEAD、OPTIO和TRACE方法自从被定义为平安的艺术后,也被定义为幂等的。参照下边关于安全的段子。

幂等性

  不要从字面意思来精通什么是幂等性,恰恰相反,那与某些作用紊乱的世界非亲非故。上边是发源维基百科的解释:

在微型Computer科学中,术语幂等用于更周密地描述三个操作,1次或频仍实行该操作产生的结果是同样的。依据使用的上下文,那可能有例外的含义。例如,在章程还是子例程调用装有副成效的景色下,意味着在率先调用之后被退换的图景也保险不改变。

  从REST服务端的角度来看,由于操作(或服务端调用)是幂等的,客户端能够用重新的调用而发生一样的结果——在编制程序语言中操作像是二个”setter”(设置)方法。换句话说,就是运用三个同样的伸手与行使单个请求效果同样。注意,当幂等操作在服务器上发出一样的结果(副功效),响应本身或许是见仁见智的(例如在多少个请求之间,财富的事态可能会退换)。

  PUT和DELETE方法被定义为是幂等的。查看http请求中delete动词的警戒消息,能够参见下文的DELETE部分。GET、HEAD、OPTIO和TRACE方法自从被定义为平安的主意后,也被定义为幂等的。参照上边关于安全的段子。

安全

  来自维基百科:

一部分情势(例如GET、HEAD、OPTIONS和TRACE)被定义为平安的主意,那象征它们仅被用来音讯搜索,而不可能退换服务器的景况。换句话说,它们不会有副功能,除了绝对来说无害的熏陶如日志、缓存、横幅广告或计数服务等。任意的GET请求,不思索使用状态的上下文,都被以为是平安的。

  可想而知,安全意味着调用的章程不会引起副效率。由此,客户端能够频仍使用安全的乞请而不用顾忌对服务端发生任何副成效。那代表服务端必须遵守GET、HEAD、OPTIONS和TRACE操作的安全概念。不然,除了对消费端发生模糊外,它还会促成Web缓存,找出引擎以及其它活动代理的主题素材——这就要服务器上爆发出人意料的后果。

  依据定义,安全操作是幂等的,因为它们在服务器上发生一样的结果。

  安全的法子被完毕为只读操作。不过,安全并不意味着服务器必须每一趟都回来同样的响应。

 

安全

  来自维基百科:

局地形式(例如GET、HEAD、OPTIONS和TRACE)被定义为安全的法子,那代表它们仅被用来音信搜索,而不可能改变服务器的景况。换句话说,它们不会有副作用,除了相对来讲无毒的影响如日志、缓存、横幅广告或计数服务等。任意的GET请求,不思虑接纳状态的上下文,都被以为是安全的。

  由此可见,安全意味着调用的主意不会挑起副作用。由此,客户端能够频仍使用安全的伸手而不用忧郁对服务端爆发任何副成效。这意味服务端必须信守GET、HEAD、OPTIONS和TRACE操作的安全概念。不然,除了对消费端发生模糊外,它还会导致Web缓存,寻找引擎以及别的活动代理的主题材料——那将要服务器上产生意料之外的后果。

  依据定义,安全操作是幂等的,因为它们在服务器上产生一样的结果。

  安全的方式被完结为只读操作。但是,安全并不意味服务器必须每一趟都回来一样的响应。

 

HTTP动词

  Http动词首要遵守“统一接口”规则,并提供给大家相应的基于名词的财富的动作。最要紧依然最常用的http动词(或然叫做方法,那样称呼或者更稳妥些)有POST、GET、PUT和DELETE。这几个分别对应于成立、读取、更新和删除(CRUD)操作。也有那3个别样的动词,可是利用频率比较低。在那个应用较少的主意中,OPTIONS和HEAD往往使用得更加多。

HTTP动词

  Http动词主要遵守“统1接口”规则,并提须求我们相应的依照名词的财富的动作。最重大依旧最常用的http动词(或许叫做方法,那样称呼或者更稳妥些)有POST、GET、PUT和DELETE。这个分别对应于创建、读取、更新和删除(CRUD)操作。也有不少任何的动词,但是利用频率比较低。在那些应用较少的方法中,OPTIONS和HEAD往往采获得更加多。

GET

  HTTP的GET方法用于检索(或读取)能源的数码。在不利的恳求路线下,GET方法会重返三个xml大概json格式的数额,以及一个200的HTTP响应代码(表示正确再次回到结果)。在错误情形下,它一般再次回到40四(不存在)或400(错误的乞求)。

  例如:

*  GET http://www.example.com/customers/12345*
  GET http://www.example.com/customers/12345/orders
  GET http://www.example.com/buckets/sample

  根据HTTP的设计规范,GET(以及附带的HEAD)请求仅用于读取数据而不改动多少。因而,那种应用情势被感到是高枕而卧的。也正是说,它们的调用未有数量修改或污染的高风险——调用1遍和调用十二次仍旧没有被调用的效益等同。其它,GET(以及HEAD)是幂等的,这表示使用多个同样的央浼与利用单个的哀求最后都怀有同等的结果。

  不要通过GET暴光不安全的操作——它应有永久都不可能修改服务器上的其他能源。

GET

  HTTP的GET方法用于检索(或读取)能源的数目。在科学的乞请路线下,GET方法会重回叁个xml只怕json格式的数额,以及三个200的HTTP响应代码(表示正确重回结果)。在错误景况下,它壹般再次来到40肆(不设有)或400(错误的乞求)。

  例如:

*  GET http://www.example.com/customers/12345*
  GET http://www.example.com/customers/12345/orders
  GET http://www.example.com/buckets/sample

  遵照HTTP的设计规范,GET(以及附带的HEAD)请求仅用于读取数据而不转移多少。由此,那种使用方法被以为是平安的。也等于说,它们的调用没有数据修改或污染的高危害——调用三回和调用1八次依旧没有被调用的功用等同。别的,GET(以及HEAD)是幂等的,那表示使用五个一样的乞请与利用单个的乞求最后都怀有同样的结果。

  不要通过GET揭露不安全的操作——它应该长久都不能够修改服务器上的别的财富。

PUT

  PUT常常被用来立异资源。通过PUT请求二个已知的能源U汉兰达I时,必要在呼吁的body中涵盖对原有财富的换代数据。

  但是,在能源ID是由客服端而非服务端提供的情事下,PUT一样能够被用来创立财富。换句话说,假如PUT请求的U奥迪Q三I中带有的财富ID值在服务器上不设有,则用于创立能源。同时呼吁的body中务必含有要成立的能源的数目。有人感觉那会暴发歧义,所以唯有真的需求,使用那种艺术来创制财富应该被慎用。

  或许我们也能够在body中提供由客户端定义的财富ID然后使用POST来创立新的财富——假诺请求的UKugaI中不分包要创制的能源ID(参见上边POST的部分)。

  例如:

*  PUT http://www.example.com/customers/12345*
  PUT http://www.example.com/customers/12345/orders/98765
  PUT http://www.example.com/buckets/secret\_stuff

  当使用PUT操作更新成功时,会再次回到200(只怕再次来到20四,表示回去的body中不含有其余内容)。假诺运用PUT请求创制财富,成功再次来到的HTTP状态码是20一。响应的body是可选的——要是提供的话将会消耗越多的带宽。在创造财富时不曾供给通过底部的任务重回链接,因为客户端已经安装了财富ID。请参见下边包车型客车再次回到值部分。

  PUT不是二个有惊无险的操作,因为它会修改(或创办)服务器上的情事,但它是幂等的。换句话说,即使你采纳PUT创设或然更新能源,然后再次调用,财富依旧存在并且状态不会爆发变化。

  例如,若是在能源增量计数器中调用PUT,那么那一个调用方法就不再是幂等的。这种状态有时候会时有发生,且恐怕能够评释它是非幂等性的。可是,提出维持PUT请求的幂等性。并强烈建议非幂等性的乞请使用POST。

PUT

  PUT平常被用来立异财富。通过PUT请求二个已知的能源U中华VI时,必要在伸手的body中隐含对原有财富的翻新数据。

  可是,在能源ID是由客服端而非服务端提供的处境下,PUT一样能够被用来创立财富。换句话说,假诺PUT请求的UXC90I中富含的财富ID值在服务器上不存在,则用来成立能源。同时伸手的body中必须含有要创设的财富的数量。有人感到那会发生歧义,所以唯有真的要求,使用那种措施来创立能源应该被慎用。

  或许大家也足以在body中提供由客户端定义的能源ID然后使用POST来创立新的能源——尽管请求的URAV4I中不分包要成立的能源ID(参见上边POST的片段)。

  例如:

*  PUT http://www.example.com/customers/12345*
  PUT http://www.example.com/customers/12345/orders/98765
  PUT http://www.example.com/buckets/secret\_stuff

  当使用PUT操作更新成功时,会重临200(或许重返20四,表示回去的body中不带有其余内容)。若是使用PUT请求创造财富,成功再次回到的HTTP状态码是20壹。响应的body是可选的——假若提供的话将会损耗越来越多的带宽。在开立财富风尚未供给通过尾部的岗位重临链接,因为客户端已经设置了能源ID。请参见上面包车型的士再次来到值部分。

  PUT不是二个平安的操作,因为它会修改(或创办)服务器上的情状,但它是幂等的。换句话说,如果您使用PUT创造或许更新能源,然后再度调用,财富依然存在并且状态不会发生变化。

  例如,要是在财富增量计数器中调用PUT,那么这些调用方法就不再是幂等的。那种景色有时候会发出,且恐怕能够表明它是非幂等性的。不过,提议维持PUT请求的幂等性。并强烈建议非幂等性的伸手使用POST。

POST

  POST请求平日被用来成立新的财富,特别是被用来创设从属资源。从属能源即归属于别的能源(如父财富)的能源。换句话说,当创立四个新能源时,POST请求发送给父能源,服务端负责将新财富与父能源开始展览关联,并分配3个ID(新财富的UEnclaveI),等等。

  例如:

  POST http://www.example.com/customers
  POST http://www.example.com/customers/12345/orders

  当创设成功时,再次来到HTTP状态码20一,并顺便2个地点头消息,当中蕴含指向起头创制的能源的链接。

  POST请求既不是安枕无忧的又不是幂等的,由此它被定义为非幂等性资源请求。使用七个同样的POST请求很大概会招致创造三个饱含一样新闻的能源。

POST

  POST请求平日被用于创造新的能源,特别是被用来创制从属能源。从属能源即归属于其它能源(如父能源)的能源。换句话说,当成立1个新财富时,POST请求发送给父能源,服务端负责将新能源与父能源开始展览关联,并分配1个ID(新能源的U奥迪Q7I),等等。

  例如:

  POST http://www.example.com/customers
  POST http://www.example.com/customers/12345/orders

  当创立成功时,再次来到HTTP状态码20一,并顺便一个职位头消息,个中带有指向起先创设的财富的链接。

  POST请求既不是高枕无忧的又不是幂等的,由此它被定义为非幂等性能源请求。使用多少个同样的POST请求异常的大概会招致创立四个饱含一样消息的财富。

PUT和POST的创制比较

  总来讲之,大家提出采纳POST来创立能源。当由客户端来决定新财富具有啥等U帕杰罗I(通过财富名称或ID)时,使用PUT:即只要客户端知道U卡宴I(或财富ID)是什么样,则对该URubiconI使用PUT请求。不然,当由服务器或服务端来调整成立的能源的U途锐I时则使用POST请求。换句话说,当客户端在创造在此以前不明白(或无法清楚)结果的U库罗德I时,使用POST请求来创建新的财富。

PUT和POST的创造比较

  可想而知,我们提议选取POST来创制财富。当由客户端来决定新能源有着何等ULX570I(通过能源名称或ID)时,使用PUT:即即便客户端知道UXC60I(或能源ID)是何许,则对该U福特ExplorerI使用PUT请求。不然,当由服务器或服务端来支配创制的财富的UHavalI时则使用POST请求。换句话说,当客户端在创设从前不领悟(或不能够知晓)结果的U福特ExplorerI时,使用POST请求来创立新的财富。

DELETE

  DELETE很轻松理解。它被用来依照ULX570I标记删除财富。

  例如:

  DELETE http://www.example.com/customers/12345
  DELETE http://www.example.com/customers/12345/orders
  DELETE http://www.example.com/buckets/sample

  当删除成功时,返回HTTP状态码200(表示正确),同时会顺手一个响应体body,body中恐怕含有了去除项的多少(那会占用部分网络带宽),或许封装的响应(参见上边的重回值)。也足以回来HTTP状态码20四(表示无内容)表示从未响应体。总来说之,能够回去状态码204表示尚未响应体,大概重临状态码200而且附带JSON风格的响应体。

  依照HTTP规范,DELETE操作是幂等的。要是你对3个财富拓展DELETE操作,财富就被移除了。在财富上多次调用DELETE最终促成的结果都同样:即财富被移除了。但倘若将DELETE的操效率于计数器(能源内部),则DETELE将不再是幂等的。如前方所述,只要数据未有被更新,计算和衡量的用法依旧可被感觉是幂等的。提出非幂等性的财富请求使用POST操作。

  不过,那里有3个有关DELETE幂等性的警戒。在三个能源上第贰回调用DELETE往往会回去404(未找到),因为该财富已经被移除了,所以找不到了。那使得DELETE操作不再是幂等的。借使能源是从数据库中剔除而不是被回顾地方统一标准记为除去,那种情状须求体面妥协。

  下表计算出了十分重要HTTP的不二秘技和财富U奇骏I,以及推荐的重临值:

HTTP请求

/customers

/customers/{id}

GET

200(正确),用户列表。使用分页、排序和过滤大导航列表。

200(正确),查找单个用户。纵然ID未有找到或ID无效则赶回404(未找到)。

PUT

404(未找到),除非您想在任何集合中革新/替换每一种财富。

200(正确)或204(无内容)。要是未有找到ID或ID无效则赶回40四(未找到)。

POST

20一(成立),带有链接到/customers/{id}的职位头音讯,包罗新的ID。

404(未找到)

DELETE

40四(未找到),除非您想删除全数集合——日常不被允许。

200(正确)。假如未有找到ID或ID无效则赶回40肆(未找到)。

 

DELETE

  DELETE很轻巧精通。它被用来依据UMuranoI标志删除财富。

  例如:

  DELETE http://www.example.com/customers/12345
  DELETE http://www.example.com/customers/12345/orders
  DELETE http://www.example.com/buckets/sample

  当删除成功时,重返HTTP状态码200(表示正确),同时会顺手1个响应体body,body中大概含有了去除项的数量(那会占用部分互连网带宽),恐怕封装的响应(参见上边包车型大巴重临值)。也得以回来HTTP状态码20肆(表示无内容)表示从未响应体。不问可见,能够回去状态码20四表示尚未响应体,也许重临状态码200同时附带JSON风格的响应体。

  依据HTTP规范,DELETE操作是幂等的。假诺你对两个财富开始展览DELETE操作,能源就被移除了。在财富上频繁调用DELETE最后促成的结果都同一:即财富被移除了。但倘使将DELETE的操成效于计数器(能源内部),则DETELE将不再是幂等的。如前方所述,只要数据尚未被更新,总计和衡量的用法依旧可被认为是幂等的。建议非幂等性的财富请求使用POST操作。

  不过,那里有1个有关DELETE幂等性的警告。在三个能源上第一次调用DELETE往往会回来40肆(未找到),因为该财富已经被移除了,所以找不到了。这使得DELETE操作不再是幂等的。假诺财富是从数据库中删除而不是被轻便地方统一标准记为除去,那种意况要求适度退让。

  下表总结出了重大HTTP的法子和能源U酷路泽I,以及引入的重回值:

HTTP请求

/customers

/customers/{id}

GET

200(正确),用户列表。使用分页、排序和过滤大导航列表。

200(正确),查找单个用户。假若ID未有找到或ID无效则赶回404(未找到)。

PUT

404(未找到),除非您想在全体集合中立异/替换各样财富。

200(正确)或20四(无内容)。借使未有找到ID或ID无效则赶回404(未找到)。

POST

20一(创建),带有链接到/customers/{id}的职位头音讯,包涵新的ID。

404(未找到)

DELETE

40四(未找到),除非你想删除全数集合——常常不被允许。

200(正确)。假若未有找到ID或ID无效则赶回40肆(未找到)。

 

能源命名

  除了适本地行使HTTP动词,在开创二个足以知道的、易于使用的Web服务API时,能源命名能够说是最富有争议和最要紧的定义。1个好的财富命名,它所对应的API看起来更加直观并且易于使用。相反,即便命名不佳,一样的API会让人认为到很愚笨并且难以精通和应用。当您需求为你的新API创设财富UHummerH二L时,那里有一些小技巧值得借鉴。

  从精神上讲,贰个RESTFul
API最后都能够被轻巧地看成是一群U纳瓦拉I的聚集,HTTP调用那么些UKoleosI以及部分用JSON和(或)XML表示的财富,它们中有不知凡几含有了相互关系的链接。RESTful的可寻址技艺根本重视UHummerH二I。每一种财富都有温馨的地点或U奥德赛I——服务器能提供的每二个实用的音信都足以视作财富来公开。统1接口的基准部分地通过ULANDI和HTTP动词的组合来化解,并符合利用正规和约定。

  在决定你系统中要动用的资源时,使用名词来定名那个能源,而不是用动词或动作来命名。换句话说,1个RESTful
UEscortI应该提到到四个现实的能源,而不是关系到一个动作。其余,名词还享有局地动词未有的属性,那也是另1个明明的要素。

  一些能源的例证:

  • 系统的用户
  • 学员注册的教程
  • 2个用户帖子的年月轴
  • 关爱别的用户的用户
  • 一篇关于骑马的稿子

  服务套件中的每种财富最少有3个UPAJEROI来标志。如若那几个U奇骏I能表示一定的意义并且能够尽量描述它所代表的财富,那么它正是多少个最佳的命名。U猎豹CS陆I应该有所可预测性和分层结构,这将力促提升它们的可精通性和可用性的:可预测指的是能源应该和称号保持1致;而分层指的是数据颇具关系上的协会。那并非REST规则或正规,可是它加重了对API的概念。

  RESTful
API是提要求消费端的。U途达I的名号和布局应当将它所发挥的意义传达给顾客。平日我们很难理解多少的边际是什么样,可是从您的数据上你应该很有望去尝试找到要赶回给客户端的数目是怎么。API是为客户端而设计的,而不是为你的数额。

  假如大家今后要讲述3个包涵客户、订单,列表项,产品等作用的订单系统。思量一下大家该怎样来描述在那个服务中所涉及到的能源的U中华VIs:

能源命名

  除了适本地行使HTTP动词,在创造三个足以通晓的、易于使用的Web服务API时,财富命名能够说是最富有争议和最主要的定义。二个好的财富命名,它所对应的API看起来越来越直观并且易于使用。相反,如若命名倒霉,同样的API会令人感到到很鲁钝并且难以掌握和运用。当您须要为您的新API创制财富U景逸SUVL时,那里有一部分小技能值得借鉴。

  从本质上讲,3个RESTFul
API最后都足以被轻便地作为是一群U酷路泽I的集纳,HTTP调用那些URubiconI以及一些用JSON和(或)XML表示的财富,它们中有过多富含了交互关系的链接。RESTful的可寻址技艺根本借助UQX56I。每一种财富都有投机的地方或U猎豹CS6I——服务器能提供的每二个有效的音信都得以当作财富来公开。统一接口的准绳部分地因此U汉兰达I和HTTP动词的组成来消除,并符合利用专业和平条约定。

  在支配你系统中要使用的财富时,使用名词来定名这么些能源,而不是用动词或动作来定名。换句话说,1个RESTful
U大切诺基I应该提到到1个有血有肉的财富,而不是涉嫌到二个动作。其余,名词还具有部分动词未有的属性,那也是另1个让人惊叹标要素。

  一些财富的例证:

  • 系统的用户
  • 学生登记的教程
  • 三个用户帖子的时刻轴
  • 关注其余用户的用户
  • 1篇关于骑马的稿子

  服务套件中的每一个能源最少有2个U奥德赛I来标记。借使这么些U奇骏I能表示肯定的意思并且能够尽量描述它所代表的能源,那么它就是叁个最棒的命名。ULacrosseI应该具有可预测性和支行结构,那将推向增长它们的可领会性和可用性的:可预测指的是财富应该和名称保持壹致;而分层指的是数额具备关系上的结构。那并非REST规则或专业,不过它加重了对API的概念。

  RESTful
API是提要求消费端的。U猎豹CS陆I的称呼和布局应当将它所发挥的意义传达给顾客。平时大家很难理解多少的分界是什么样,不过从你的数码上您应该很有异常的大希望去尝尝找到要赶回给客户端的多少是怎么。API是为客户端而设计的,而不是为您的多寡。

  借使大家前天要描述多少个回顾客户、订单,列表项,产品等作用的订单系统。惦念一下我们该如何来讲述在那一个服务中所涉及到的能源的USportageIs:

资源URI示例

  为了在系统中插入(创制)一个新的用户,我们得以接纳:

  POST http://www.example.com/customers

 

  读取编号为33二四五的用户音讯:

  GET http://www.example.com/customers/33245

  使用PUT和DELETE来请求同样的U普拉多I,能够立异和删除数据。

 

  上边是对产品有关的U福特ExplorerI的部分建议:

  POST http://www.example.com/products

  用于创造新的产品。

 

  GET|PUT|DELETE http://www.example.com/products/66432

  分别用于读取、更新、删除编号为6643二的产品。

 

  那么,怎么样为用户创设一个新的订单呢?

  1种方案是:

  POST http://www.example.com/orders

  那种办法可以用来创设订单,但贫乏相应的用户数据。

  

  因为大家想为用户成立二个订单(注意之间的关系),那么些U福睿斯I只怕不够直观,上边那么些UTiggoI则更清楚一些:

  POST http://www.example.com/customers/33245/orders

  现在大家领悟它是为编号3324伍的用户创设三个订单。

 

  那上边那么些请求重回的是如何啊?

  GET http://www.example.com/customers/33245/orders

  恐怕是3个号码为33二四5的用户所创设或享有的订单列表。注意:大家能够遮挡对该USportageI举行DELETE或PUT请求,因为它的操作对象是一个成团。

 

  继续浓厚,那上边这些UPAJEROI的呼吁又象征如何吧?

  POST http://www.example.com/customers/33245/orders/8769/lineitems

  大概是(为编号33二肆5的用户)扩张1个号码为876玖的订单条目。没有错!假使应用GET格局呼吁那几个U冠道I,则会重返这么些订单的有所条条框框。然而,借使那个条款与用户消息非亲非故,大家将会提供POST
www.example.com/orders/8769/lineitems
这个URI。

  从再次来到的那几个条款来看,钦命的能源或者会有多少个U奇骏Is,所以大家或许也亟供给提供这样3个ULX570I
GET
http://www.example.com/orders/8769
,用来在不知情用户ID的情景下基于订单ID来查询订单。

 

  更进一步:

  GET http://www.example.com/customers/33245/orders/8769/lineitems/1

  也许只回去同个订单中的第3个条目。

  未来您应有通晓什么是分层结构了。它们并不是从严的平整,只是为了保障在你的劳务中这几个强制的结构能够更便于被用户所领悟。与富有软件开辟中的技术同样,命名是马到成功的最首要。

  

  多看有个别API的演示并学会调节那个技艺,和你的队友一齐来完善你API能源的U奥迪Q7Is。那里有一对APIs的事例:

资源URI示例

  为了在系统中插入(创立)多个新的用户,大家能够利用:

  POST http://www.example.com/customers

 

  读取编号为332四五的用户新闻:

  GET http://www.example.com/customers/33245

  使用PUT和DELETE来请求一样的U奥迪Q5I,能够立异和删除数据。

 

  下边是对成品有关的UCR-VI的片段建议:

  POST http://www.example.com/products

  用于创建新的成品。

 

  GET|PUT|DELETE http://www.example.com/products/66432

  分别用于读取、更新、删除编号为6643二的出品。

 

  那么,如何为用户创立3个新的订单呢?

  壹种方案是:

  POST http://www.example.com/orders

  那种办法得以用来创立订单,但贫乏相应的用户数量。

  

  因为我们想为用户成立一个订单(注意之间的涉嫌),那一个UGL450I大概不够直观,上面那些UHummerH二I则更清楚壹些:

  POST http://www.example.com/customers/33245/orders

  现在我们掌握它是为编号33245的用户创制2个订单。

 

  这下边这一个请求再次来到的是如何吗?

  GET http://www.example.com/customers/33245/orders

  大概是一个号码为33二肆伍的用户所开创或持有的订单列表。注意:大家得以屏蔽对该U奥迪Q5I进行DELETE或PUT请求,因为它的操作对象是三个会见。

 

  继续深刻,那上边这些U中华VI的恳求又代表如何啊?

  POST http://www.example.com/customers/33245/orders/8769/lineitems

  可能是(为编号33二4伍的用户)扩展三个数码为876九的订单条目。没有错!要是选取GET方式呼吁那么些U牧马人I,则会回来这么些订单的具有条条框框。可是,借使那么些条款与用户新闻无关,我们将会提供POST
www.example.com/orders/8769/lineitems
这个URI。

  从重临的这一个条款来看,钦赐的资源大概会有多少个U牧马人Is,所以大家或者也亟需求提供这样多少个U凯雷德I
GET
http://www.example.com/orders/8769
,用来在不知晓用户ID的事态下基于订单ID来询问订单。

 

  更进一步:

  GET http://www.example.com/customers/33245/orders/8769/lineitems/1

  也许只回去同个订单中的第1个条文。

  以后您应当通晓什么是分层构造了。它们并不是严谨的条条框框,只是为了保险在你的劳动中这一个强制的组织能够更便于被用户所知晓。与拥有软件开荒中的本事同样,命名是成功的要害。

  

  多看有的API的以身作则并学会调整这几个本领,和你的队友一同来周详你API能源的URAV4Is。那里有1部分APIs的例子:

能源命名的反例

  前边我们早就切磋过局地适用的财富命名的例证,然则有时一些反面的事例也很有教育意义。下边是一对不太具备RESTful风格的财富ULANDIs,看起来比较散乱。那几个都以不对的事例! 

  首先,一些serivices往往利用单一的U本田CR-VI来内定服务接口,然后通过查询参数来内定HTTP请求的动作。例如,要立异编号12345的用户新闻,带有JSON
body的乞求大概是这么:

  GET
http://api.example.com/services?op=update\_customer&id=12345&format=json

  固然地点ULacrosseL中的”services”的这一个节点是多少个名词,但以此UENCOREL不是自解释的,因为对此有着的请求来讲,该U君越I的层级结构都以平等的。其它,它应用GET作为HTTP动词来实践一个立异操作,那简直就是反人类(甚至是触机便发的)。

  上面是别的二个更新用户的操作的事例:

  GET http://api.example.com/update\_customer/12345

  以及它的二个变种:

  GET http://api.example.com/customers/12345/update

  你会时不时看看在其他开辟者的劳动套件中有多数那样的用法。能够看来,那些开垦者试图去创造RESTful的财富名称,而且已经有了部分发展。但是你仍旧能够辨识出ULANDL中的动词短语。注意,在这几个UCR-VL中大家不须求”update”这一个词,因为大家能够借助HTTP动词来成功操作。下面这几个URAV4L正好表达了那一点:

  PUT http://api.example.com/customers/12345/update

  那些请求同时存在PUT和”update”,那会对消费者发生迷惑!那里的”update”指的是一个财富吗?因此,那里大家费些口舌也是指望您可见知道……

财富命名的反例

  前边大家早就切磋过部分适用的财富命名的例子,然则有时1些反面包车型大巴例证也很有教育意义。上面是部分不太具备RESTful风格的财富UOdysseyIs,看起来比较混乱。这几个皆以错误的例证! 

  首先,一些serivices往往选用单壹的U悍马H二I来钦点服务接口,然后经过查询参数来钦点HTTP请求的动作。例如,要立异编号123肆伍的用户消息,带有JSON
body的请求只怕是如此:

  GET
http://api.example.com/services?op=update\_customer&id=12345&format=json

  就算地点U兰德EscortL中的”services”的这么些节点是二个名词,但这一个U路虎极光L不是自解释的,因为对此持有的伸手来讲,该U揽胜I的层级结构都以壹律的。其它,它应用GET作为HTTP动词来实践叁个更新操作,那大致正是反人类(甚至是危险的)。

  上面是其余叁个更新用户的操作的例子:

  GET http://api.example.com/update\_customer/12345

  以及它的二个变种:

  GET http://api.example.com/customers/12345/update

  你会经常来看在别的开荒者的劳动套件中有成都百货上千这么的用法。能够看到,那一个开辟者试图去创建RESTful的财富名称,而且早已有了部分升华。可是你依然能够辨识出U哈弗L中的动词短语。注意,在那一个U奥德赛L中大家不需求”update”那么些词,因为大家得以凭借HTTP动词来成功操作。下边这一个URubiconL正好表明了那或多或少:

  PUT http://api.example.com/customers/12345/update

  那么些请求同时设有PUT和”update”,那会对顾客发生吸引!那里的”update”指的是贰个财富吗?由此,那里大家费些口舌也是可望你能够知情……

复数

  让大家来研究一下复数和“单数”的争辩…还没据书上说过?但那种争议确实存在,事实上它能够总结为那个主题素材……

  在您的层级结构中UPRADOI节点是不是供给被命名字为单数或复数情势呢?举个例证,你用来查找用户能源的U哈弗I的命名是还是不是要求像下边那样:

  GET http://www.example.com/customer/33245

  或者:

  GET http://www.example.com/customers/33245

  三种艺术都没难题,但常见大家都会选用使用复数命名,以使得你的API
U君越I在全部的HTTP方法中保持1致。原因是依照那样壹种思考:customers是劳务套件中的一个成团,而ID33贰肆伍的这一个用户则是其一集合中的在那之中一个。

  根据这么些规则,1个应用复数格局的多节点的U宝马X3I会是如此(注意粗体部分):

  GET
http://www.example.com/**customers**/33245/**orders**/8769/**lineitems**/1

  “customers”、“orders”以及“lineitems”那么些URAV肆I节点都选用的是复数方式。

  那意味你的各类根能源只需求多个大旨的URubiconL就足以了,多个用于创制集合内的财富,另二个用来依据标志符获取、更新和删除财富。例如,以customers为例,创立财富能够运用上面包车型客车U奇骏L进行操作:

  POST http://www.example.com/customers

  而读取、更新和删除能源,使用上面包车型大巴U奥迪Q7L操作:

  GET|PUT|DELETE http://www.example.com/customers/{id}

  正如前方提到的,给定的能源大概有多个ULANDI,但作为贰个微小的完整的增加和删除改查作用,利用三个简易的U凯雷德I来处理就够了。

  或者你会问:是还是不是在有点景况下复数没有趣?嗯,事实上是如此的。当未有集合概念的时候(此时复数没风趣)。换句话说,当财富唯有1个的景观下,使用单数财富名称也是足以的——即3个单①的财富。例如,倘诺有八个纯粹的完全体署能源,你可以使用一个单数名称来表示:

  GET|PUT|DELETE http://www.example.com/configuration

  注意那里贫乏configuration的ID以及HTTP动词POST的用法。假使每种用户有1个安顿来说,那么那么些UMuranoL会是那样:

  GET|PUT|DELETE
http://www.example.com/customers/12345/configuration

  一样令人瞩目那里未有点名configuration的ID,以及从未给定POST动词的用法。在那四个例子中,大概也会有人以为选拔POST是行得通的。好吧…

 

复数

  让我们来探讨一下复数和“单数”的争辨…还没传闻过?但那种争议确实存在,事实上它能够归纳为那个标题……

  在你的层级结构中U逍客I节点是或不是需求被取名字为单数或复数形式呢?举个例子,你用来寻找用户能源的URubiconI的命名是或不是须求像上面那样:

  GET http://www.example.com/customer/33245

  或者:

  GET http://www.example.com/customers/33245

  三种情势都没难题,但日常我们都会选取使用复数命名,以使得你的API
UPRADOI在颇具的HTTP方法中保持一致。原因是依据那样一种驰念:customers是服务套件中的一个聚众,而ID33贰肆伍的那么些用户则是那个集合中的在那之中二个。

  依据这些规则,3个用到复数方式的多节点的URI会是那般(注意粗体部分):

  GET
http://www.example.com/**customers**/33245/**orders**/8769/**lineitems**/1

  “customers”、“orders”以及“lineitems”这个U卡宴I节点都应用的是复数情势。

  那意味着你的各类根财富只要求多少个主导的U奥迪Q7L就足以了,一个用以成立集合内的能源,另三个用来依照标记符获取、更新和删除能源。例如,以customers为例,创制财富能够行使上面包车型地铁UCR-VL进行操作:

  POST http://www.example.com/customers

  而读取、更新和删除能源,使用上边包车型客车UTucsonL操作:

  GET|PUT|DELETE http://www.example.com/customers/{id}

  正如前方提到的,给定的财富可能有五个USportageI,但作为多少个微小的壹体化的增加和删除改查作用,利用七个大致的U卡宴I来拍卖就够了。

  恐怕你会问:是还是不是在有点情况下复数没有趣?嗯,事实上是如此的。当未有集合概念的时候(此时复数没有意义)。换句话说,当能源唯有三个的情事下,使用单数能源名称也是能够的——即两个纯粹的能源。例如,要是有3个纯净的欧洲经济共同体布局能源,你能够使用多少个单数名称来代表:

  GET|PUT|DELETE http://www.example.com/configuration

  注意那里贫乏configuration的ID以及HTTP动词POST的用法。假诺每一个用户有1个安插来讲,那么这些USportageL会是这么:

  GET|PUT|DELETE
http://www.example.com/customers/12345/configuration

  同样令人瞩目那里未有点名configuration的ID,以及未有给定POST动词的用法。在那五个例证中,只怕也会有人以为利用POST是实用的。好吧…

 

回到表征

  正如前方提到的,RESTful接口协理两种能源特点,包罗JSON和XML,以及被打包的JSON和XML。提议JSON作为暗中同意表征,不过服务端应该允许客户端钦点别的表征。

  对于客户端请求的特色格式,大家能够在Accept头通过文件扩张名来举办点名,也能够经过query-string等其余措施来钦定。理想状态下,服务端能够支撑具有那一个方法。不过,以后专业更赞成于通过类似于文件扩大名的格局来拓展点名。因而,建议服务端至少须求补助选用文件增加名的法子,例如“.json”,“.xml”以及它们的包装版本“.wjon”,“.wxml”。

  通过那种艺术,在URI中钦命再次来到表征的格式,能够加强UHighlanderL的可知性。例如,GET
http://www.example.com/customers.xml
将赶回customer列表的XML格式的天性。同样,GET
http://www.example.com/customers.json
将赶回3个JSON格式的性状。那样,固然是在最基础的客户端(例如“curl”),服务应用起来也会进一步简便易行。推荐使用那种方法。

  别的,当url中一贯不包蕴格式表明时,服务端应该回到暗许格式的特征(如若为JSON)。例如:

  GET http://www.example.com/customers/12345

  GET http://www.example.com/customers/12345.json

  以上两者重返的ID为12345的customer数据均为JSON格式,那是服务端的暗中认可格式。

  GET http://www.example.com/customers/12345.xml

  借使服务端接济的话,以上请求重回的ID为12345的customer数据为XML格式。假若该服务器不支持XML格式的能源,将赶回三个HTTP
404的荒谬。

  使用HTTP
Accept头被大规模以为是1种更优雅的法子,并且符合HTTP的正经和意义,客户端能够经过那种措施来报告HTTP服务端它们可支持的数据类型有哪些。然而,为了采纳Accept头,服务端要同时辅助封装和未封装的响应,你无法不贯彻自定义的品类——因为那一个格式不是正统的类型。那大大扩大了客户端和服务端的繁杂。请参见奥迪Q5FC
2616的1肆.壹节关于Accept头的详细新闻(http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1)。使用文件扩展名来钦点数量格式是最轻巧易行直接的措施,用最少的字符就能够成功,并且援助脚本操作——无需利用HTTP头。

  常常当大家提到REST服务,跟XML是非亲非故的。尽管服务端补助XML,也大致未有人提出在REST中应用XML。XML的行业内部和公约在REST中不太适用。尤其是它连命名空间都不曾,就更不应当在RESTful服务系列中运用了。那只会使业务变得更扑朔迷离。所以回来的XML看起来更像JSON,它回顾易读,未有格局和命名空间的限量,换句话来讲是无标准的,易于解析。

回来表征

  正如前方提到的,RESTful接口扶助二种财富特色,包罗JSON和XML,以及被卷入的JSON和XML。提出JSON作为默许表征,可是服务端应该允许客户端钦赐其余表征。

  对于客户端请求的特征格式,大家得以在Accept头通过文件扩展名来拓展点名,也得以因此query-string等别的情势来钦点。理想状态下,服务端能够援助全体这么些艺术。可是,以后标准更赞成于通过类似于文件扩充名的形式来拓展点名。因而,建议服务端至少须求协助使用文件扩充名的法子,例如“.json”,“.xml”以及它们的包裹版本“.wjon”,“.wxml”。

  通过那种艺术,在U福特ExplorerI中钦点重返表征的格式,能够拉长U中华VL的可知性。例如,GET
http://www.example.com/customers.xml
将赶回customer列表的XML格式的特点。同样,GET
http://www.example.com/customers.json
将赶回三个JSON格式的表征。那样,尽管是在最基础的客户端(例如“curl”),服务使用起来也会愈加方便人民群众。推荐应用那种艺术。

  其它,当url中平素不包蕴格式表达时,服务端应该回到暗许格式的特征(要是为JSON)。例如:

  GET http://www.example.com/customers/12345

  GET http://www.example.com/customers/12345.json

  以上两者再次回到的ID为12345的customer数据均为JSON格式,那是服务端的私下认可格式。

  GET http://www.example.com/customers/12345.xml

  假如服务端协助的话,以上请求再次回到的ID为12345的customer数据为XML格式。倘诺该服务器不协理XML格式的财富,将回到一个HTTP
40四的荒谬。

  使用HTTP
Accept头被大面积以为是壹种更优雅的办法,并且符合HTTP的正经和含义,客户端能够经过这种办法来告诉HTTP服务端它们可协助的数据类型有啥。不过,为了接纳Accept头,服务端要同时辅助封装和未封装的响应,你不能够不贯彻自定义的档次——因为那一个格式不是正规的种类。那大大扩充了客户端和服务端的繁杂。请参见智跑FC
2616的1四.1节关于Accept头的详细消息(http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1)。使用文件扩充名来钦点数量格式是最简单易行直接的措施,用最少的字符就可以实现,并且援助脚本操作——无需采纳HTTP头。

  平常当大家提到REST服务,跟XML是毫无干系的。纵然服务端资助XML,也差不多平昔不人建议在REST中采取XML。XML的正儿8经和公约在REST中不太适用。尤其是它连命名空间都并未有,就更不应该在RESTful服务连串中动用了。那只会使业务变得更扑朔迷离。所以回来的XML看起来更像JSON,它总结易读,未有情势和命名空间的范围,换句话来讲是无标准的,易于解析。

能源通过链接的可发现性(HATEOAS续)

  REST指导标准之壹(根据统一接口规范)是application的情状通过hypertext(超文本)来传输。那正是大家一般所说的Hypertext
As The Engine of Application State
(即HATEOAS,用超文本来作为应用程序状态机),大家在“REST是什么”一节中也论及过。

  依照RoyFielding在他的博客中的描述(http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertextdriven),REST接口中最重视的壹些是超文本的选择。此外,他还建议,在提交任何有关的新闻在此之前,三个API应该是可用和可分晓的。也正是说,三个API应当能够由此其链接导航到数码的相继部分。不建议只回去纯数据。

  然则当下的产业界先驱们并未有平日利用那种做法,那反映了HATEOAS仅仅在成熟度模型中的使用率更加高。纵客官多的服务种类,它们多数重临越来越多的多少,而回到的链接却很少(或许未有)。那是违反Fielding的REST约定的。Fielding说:“音讯的每3个可寻址单元都引导一个地方……查询结果应当突显为3个暗含摘要音讯的链接清单,而不是目的数组。”

  另一方面,轻易狠毒地将总体链接集合重回会大大影响互联网带宽。在实际处境中,依照所需的规范或选用情形,API接口的通讯量要依照服务器响应中中国足球球组织一级联赛文本链接所包括的“摘要”数量来平衡。

  同时,丰富利用HATEOAS恐怕会增加完毕的繁杂,并对服务客户端发生强烈的承受,这一定于下跌了客户端和劳动器端开辟职员的生产力。因而,当务之急是要平衡超链接服务实行和现存可用能源之间的主题素材。

  超链接最小化的做法是在最大限度地收缩客户端和服务器之间的耦合的还要,提升服务端的可用性、可垄断性和可精通性。这么些最小化提出是:通过POST创立财富并从GET请求重回集合,对于有分页的景观前面我们会涉及。

财富通过链接的可发现性(HATEOAS续)

  REST辅导标准之一(依照联合接口规范)是application的情状通过hypertext(超文本)来传输。那便是大家1般所说的Hypertext
As The Engine of Application State
(即HATEOAS,用超文本来作为应用程序状态机),大家在“REST是什么”1节中也波及过。

  依照罗伊Fielding在他的博客中的描述(http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertextdriven),REST接口中最要害的局地是超文本的选用。其它,他还提出,在付出任何有关的新闻从前,三个API应该是可用和可领略的。约等于说,三个API应当能够经过其链接导航到多少的种种部分。不提出只回去纯数据。

  不过当下的产业界先驱们并不曾平日利用那种做法,那显示了HATEOAS仅仅在成熟度模型中的使用率越来越高。纵客官多的服务连串,它们多数再次回到愈多的多寡,而回到的链接却很少(恐怕尚未)。这是反其道而行之菲尔德ing的REST约定的。Fielding说:“音讯的每三个可寻址单元都带领二个地址……查询结果应该显示为四个分包摘要新闻的链接清单,而不是目的数组。”

  另壹方面,简单残忍地将全体链接集合重返会大大影响网络带宽。在其实际情形况中,依照所需的尺度或应用情状,API接口的通讯量要基于服务器响应中中国足球球组织一级联赛文本链接所蕴藏的“摘要”数量来平衡。

  同时,丰盛利用HATEOAS大概会大增完成的扑朔迷离,并对服务客户端爆发强烈的承负,这一定于降低了客户端和劳动器端开垦职员的生产力。由此,当劳之急是要平衡超链接服务执行和现有可用财富之间的难点。

  超链接最小化的做法是在最大限度地回落客户端和服务器之间的耦合的同时,升高服务端的可用性、可垄断(monopoly)性和可明白性。这几个最小化建议是:通过POST创造能源并从GET请求再次来到集合,对于有分页的情状后边大家会提到。

小小的化链接推荐

  在create的用例中,新建财富的U科雷傲I(链接)应该在Location响应头中回到,且响应主题是空的——或许只含有新建能源的ID。

  对于从服务端再次来到的特征集合,各类表征应该在它的链接集合中指点1个纤维的“自个儿”链接属性。为了方便分页操作,别的的链接能够投身四个独立的链接集合中回到,要求时能够分包“第三页”、“上1页”、“下一页”、“最终1页”等音信。

  参照下文链接格式部分的例子获取愈多音信。

小小的化链接推荐

  在create的用例中,新建能源的U景逸SUVI(链接)应该在Location响应头中回到,且响应中央是空的——也许只含有新建能源的ID。

  对于从服务端再次来到的特征集合,每一个表征应该在它的链接集合中教导一个纤维的“自身”链接属性。为了方便分页操作,其余的链接能够献身1个独门的链接集合中回到,供给时得以分包“第二页”、“上1页”、“下壹页”、“最终一页”等消息。

  参照下文链接格式一些的例子获取更加多新闻。

链接格式

  参照整个链接格式的专业,建议遵从1些接近Atom、AtomPub或Xlink的作风。JSON-LD也不错,但并未有被大规模运用(借使已经被用过)。近日标准最广大的情势是行使带有”rel”成分和含有财富全体USportageI的”href”元素的Atom链接格式,不分包别的身份验证或询问字符串参数。”rel”成分得以包含标准值”alternate”、”related”、”self”、”enclosure”和”via”,还有分页链接的“第三页”、“上1页”、“下1页”,“最终一页”。在急需时得以自定义并加上应用它们。

  一些XML
Atom格式的定义对于用JSON格式表示的链接来说是不著见效的。例如,METHOD属性对于一个RESTful财富来说是不要求的,因为对于三个加以的财富,在富有帮衬的HTTP方法(CRUD行为)中,财富的U揽胜极光I都以同一的——所以单独列出这个是绝非须要的。

  让大家举一些具体的事例来特别表达那点。上边是调用成立新能源的伏乞后的响应:

  POST http://api.example.com/users

  下面是响应头集合中蕴藏创制新能源的UENCOREI的Location部分:

HTTP/1.1 201 CREATED 
Status: 201 
Connection: close 
Content-Type: application/json; charset=utf-8 
Location: http://api.example.com/users/12346

  重临的body可感到空,也许隐含1个被包裹的响应(见下文封装响应)。

  下边包车型客车事例通过GET请求获取壹个不带有分页的特征集合的JSON响应:

{
  "data": [
    {
      "user_id": "42",
      "name": "Bob",
      "links": [
        {
          "rel": "self",
          "href": "http://api.example.com/users/42"
        }
      ]
    },
    {
      "user_id": "22",
      "name": "Frank",
      "links": [
        {
          "rel": "self",
          "href": "http://api.example.com/users/22"
        }
      ]
    },
    {
      "user_id": "125",
      "name": "Sally",
      "links": [
        {
          "rel": "self",
          "href": "http://api.example.com/users/125"
        }
      ]
    }
  ]
}

  注意,links数组中的每1项都饱含二个针对“本人(self)”的链接。该数组还可能还富含其余关系,如children、parent等。

  最后七个例证是通过GET请求获取1个富含分页的性状集合的JSON响应(每页呈现3项),大家付出第壹页的数量:

{
  "data": [
    {
      "user_id": "42",
      "name": "Bob",
      "links": [
        {
          "rel": "self",
          "href": "http://api.example.com/users/42"
        }
      ]
    },
    {
      "user_id": "22",
      "name": "Frank",
      "links": [
        {
          "rel": "self",
          "href": "http://api.example.com/users/22"
        }
      ]
    },
    {
      "user_id": "125",
      "name": "Sally",
      "links": [
        {
          "rel": "self",
          "href": "http://api.example.com/users/125"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "first",
      "href": "http://api.example.com/users?offset=0&limit=3"
    },
    {
      "rel": "last",
      "href": "http://api.example.com/users?offset=55&limit=3"
    },
    {
      "rel": "previous",
      "href": "http://api.example.com/users?offset=3&limit=3"
    },
    {
      "rel": "next",
      "href": "http://api.example.com/users?offset=9&limit=3"
    }
  ]
}

  在这些事例中,响应中用于分页的links集合中的每1项都饱含二个针对性“自个儿(self)”的链接。那里只怕还会有部分事关到集结的别的链接,但都与分页自身非亲非故。简单的讲,那里有五个地点含有links。2个正是data对象中所包蕴的聚集(那几个也是接口要回到给客户端的数额表征集合),个中的每1项至少要包涵一个针对性“本身(self)”的links集合;另几个则是多个独立的指标links,个中囊括和分页相关的链接,该片段的始末适用于1切集合。

  对于由此POST请求创造能源的情况,须要在响应头中包括一个关联新建对象链接的Location

链接格式

  参照整个链接格式的标准,建议遵循壹些好像Atom、AtomPub或Xlink的品格。JSON-LD也不易,但并没有被周围选择(若是已经被用过)。最近专业最广泛的不二秘诀是使用含有”rel”元素和含有财富全体U奥迪Q叁I的”href”成分的Atom链接格式,不分包其余身份验证或询问字符串参数。”rel”成分得以涵盖标准值”alternate”、”related”、”self”、”enclosure”和”via”,还有分页链接的“第三页”、“上1页”、“下壹页”,“最终1页”。在须求时能够自定义并加上应用它们。

  壹些XML
Atom格式的概念对于用JSON格式表示的链接来说是不行的。例如,METHOD属性对于三个RESTful能源来讲是不须求的,因为对此贰个加以的能源,在有着扶助的HTTP方法(CRUD行为)中,能源的URubiconI都以同样的——所以单独列出那些是一直不必要的。

  让大家举1些具体的事例来更是表达那一点。上边是调用创制新能源的请求后的响应:

  POST http://api.example.com/users

  上边是响应头集合中包罗创立新财富的USportageI的Location部分:

HTTP/1.1 201 CREATED 
Status: 201 
Connection: close 
Content-Type: application/json; charset=utf-8 
Location: http://api.example.com/users/12346

  重回的body可认为空,可能隐含一个被包裹的响应(见下文封装响应)。

  上边包车型大巴例证通过GET请求获取2个不包罗分页的特点集合的JSON响应:

{
  "data": [
    {
      "user_id": "42",
      "name": "Bob",
      "links": [
        {
          "rel": "self",
          "href": "http://api.example.com/users/42"
        }
      ]
    },
    {
      "user_id": "22",
      "name": "Frank",
      "links": [
        {
          "rel": "self",
          "href": "http://api.example.com/users/22"
        }
      ]
    },
    {
      "user_id": "125",
      "name": "Sally",
      "links": [
        {
          "rel": "self",
          "href": "http://api.example.com/users/125"
        }
      ]
    }
  ]
}

  注意,links数组中的每一项都饱含一个针对性“自个儿(self)”的链接。该数组还或然还包括其余关系,如children、parent等。

  最终贰个例证是因而GET请求获取3个富含分页的性状集合的JSON响应(每页展现三项),大家付出第二页的数目:

{
  "data": [
    {
      "user_id": "42",
      "name": "Bob",
      "links": [
        {
          "rel": "self",
          "href": "http://api.example.com/users/42"
        }
      ]
    },
    {
      "user_id": "22",
      "name": "Frank",
      "links": [
        {
          "rel": "self",
          "href": "http://api.example.com/users/22"
        }
      ]
    },
    {
      "user_id": "125",
      "name": "Sally",
      "links": [
        {
          "rel": "self",
          "href": "http://api.example.com/users/125"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "first",
      "href": "http://api.example.com/users?offset=0&limit=3"
    },
    {
      "rel": "last",
      "href": "http://api.example.com/users?offset=55&limit=3"
    },
    {
      "rel": "previous",
      "href": "http://api.example.com/users?offset=3&limit=3"
    },
    {
      "rel": "next",
      "href": "http://api.example.com/users?offset=9&limit=3"
    }
  ]
}

  在这几个例子中,响应中用于分页的links集合中的各样都含有一个针对性“本人(self)”的链接。那里或然还会有局地涉嫌到聚集的别的链接,但都与分页自个儿非亲非故。一句话来讲,那里有七个地方含有links。二个便是data对象中所包涵的会见(那么些也是接口要重临给客户端的数目表征集合),个中的每1项至少要包含1个针对性“自个儿(self)”的links集合;另二个则是3个单身的指标links,当中囊括和分页相关的链接,该片段的始末适用于漫天集合。

  对于通过POST请求创建财富的状态,要求在响应头中包括三个涉及新建对象链接的Location

包裹响应

   服务器能够在响应中同时再次回到HTTP状态码和body。有许多JavaScript框架没有把HTTP状态响应码重回给最后的开拓者,那频仍会招致客户端不只怕遵照气象码来鲜明具体的行为。此外,固然HTTP规范中有很各类响应码,不过反复唯有少数客户端会关切那么些——常常大家只在乎”success”、”error”或”failture”。由此,将响应内容和响应状态码封装在含有响应音讯的表征中,是有供给的。

  OmniTI
实验室有诸如此类三个建议,它被称之为JSEND响应。越多新闻请参考http://labs.omniti.com/labs/jsend。其它1个提案是由DouglasCrockford提议的,能够查看这里http://www.json.org/JSONRequest.html

  这一个提案在实行中并未完全涵盖全部的情状。基本上,今后最佳的做法是鲁人持竿以下属性封装常规(非JSONP)响应:

  • code——包蕴三个整数门类的HTTP响应状态码。
  • status——包蕴文本:”success”,”fail”或”error”。HTTP状态响应码在500-59九之间为”fail”,在400-499里边为”error”,别的均为”success”(例如:响应状态码为壹XX、2XX和三XX)。
  • message——当状态值为”fail”和”error”时有效,用于呈现错误音讯。参照国际化(il8n)标准,它能够涵盖音信号恐怕编码,能够只包涵个中三个,大概同时富含并用分隔符隔断。
  • data——包蕴响应的body。当状态值为”fail”或”error”时,data仅包括错误原因或尤其名称。

  下边是1个回去success的包裹响应:

{
  "code": 200,
  "status": "success",
  "data": {
    "lacksTOS": false,
    "invalidCredentials": false,
    "authToken": "4ee683baa2a3332c3c86026d"
  }
}

  重临error的包裹响应:

{
  "code": 401,
  "status": "error",
  "message": "token is invalid",
  "data": "UnauthorizedException"
}

  那四个包裹响应对应的XML如下:

<response>
    <code>200</code>
    <status>success</status>
    <data class="AuthenticationResult">
        <lacksTOS>false</lacksTOS>
        <invalidCredentials>false</invalidCredentials>
        <authToken>1.0|idm|idm|4ee683baa2a3332c3c86026d</authToken>
    </data>
</response>

  和:

<response>
    <code>401</code>
    <status>error</status>
    <message>token is invalid</message>
    <data class="string">UnauthorizedException</data>
</response>

包裹响应

   服务器能够在响应中并且重临HTTP状态码和body。有数不胜数JavaScript框架未有把HTTP状态响应码再次回到给最后的开拓者,那频仍会形成客户端无法依据情状码来明确具体的一举一动。别的,就算HTTP规范中有很种种响应码,可是频仍只有些客户端会关心这么些——经常我们只在乎”success”、”error”或”failture”。因而,将响应内容和响应状态码封装在富含响应音讯的性状中,是有至关重要的。

  OmniTI
实验室有这么一个提出,它被称之为JSEND响应。越来越多音讯请参考http://labs.omniti.com/labs/jsend。别的二个提案是由DouglasCrockford提议的,能够查看这里http://www.json.org/JSONRequest.html

  那一个提案在实施中并未完全涵盖全部的动静。基本上,未来最棒的做法是安份守己以下属性封装常规(非JSONP)响应:

  • code——包括3个平头项指标HTTP响应状态码。
  • status——包括文本:”success”,”fail”或”error”。HTTP状态响应码在500-59玖里边为”fail”,在400-49九里头为”error”,别的均为”success”(例如:响应状态码为壹XX、二XX和三XX)。
  • message——当状态值为”fail”和”error”时有效,用于突显错误消息。参照国际化(il八n)标准,它能够包括消息号恐怕编码,能够只含有个中3个,或许同时涵盖并用分隔符隔绝。
  • data——包蕴响应的body。当状态值为”fail”或”error”时,data仅包蕴错误原因或尤其名称。

  上边是一个赶回success的包裹响应:

{
  "code": 200,
  "status": "success",
  "data": {
    "lacksTOS": false,
    "invalidCredentials": false,
    "authToken": "4ee683baa2a3332c3c86026d"
  }
}

  重临error的卷入响应:

{
  "code": 401,
  "status": "error",
  "message": "token is invalid",
  "data": "UnauthorizedException"
}

  那三个包裹响应对应的XML如下:

<response>
    <code>200</code>
    <status>success</status>
    <data class="AuthenticationResult">
        <lacksTOS>false</lacksTOS>
        <invalidCredentials>false</invalidCredentials>
        <authToken>1.0|idm|idm|4ee683baa2a3332c3c86026d</authToken>
    </data>
</response>

  和:

<response>
    <code>401</code>
    <status>error</status>
    <message>token is invalid</message>
    <data class="string">UnauthorizedException</data>
</response>

拍卖跨域难题

   大家都听大人讲过关于浏览器的同源计谋或同源性须求。它指的是浏览器只好请求当前正在突显的站点的财富。例如,要是当前正在突显的站点是www.Example1.com,则该站点不能够对www.Example.com提倡呼吁。分明那会潜移默化站点访问服务器的法子。

  近来有多个被广泛接受的支撑跨域请求的格局:JSONP和跨域能源共享(CO奥迪Q三S)。JSONP或“填充的JSON”是1种选拔形式,它提供了2个措施请求来自分化域中的服务器的数据。其行事方式是从服务器再次来到任意的JavaScript代码,而不是JSON。客户端的响应由JavaScript解析器进行辨析,而不是一向解析JSON数据。别的,CO猎豹CS陆S是壹种web浏览器的技术专业,它为web服务器定义了壹种方法,从而允许服务器的能源能够被差别域的网页访问。CO猎豹CS陆S被当作是JSONP的风行代替品,并且能够被有着今世浏览器帮衬。由此,不提出利用JSONP。任何境况下,推荐选拔CO讴歌MDXS。

处理跨域难点

   大家都闻讯过有关浏览器的同源战略或同源性要求。它指的是浏览器只好请求当前正值展现的站点的能源。例如,假若当前正在呈现的站点是www.Example1.com,则该站点不可能对www.Example.com倡议呼吁。鲜明那会影响站点访问服务器的法子。

  近来有多个被普及接受的支撑跨域请求的方式:JSONP和跨域财富共享(COCRUISERS)。JSONP或“填充的JSON”是1种选拔形式,它提供了一个格局请求来自差异域中的服务器的数目。其职业章程是从服务器重返任意的JavaScript代码,而不是JSON。客户端的响应由JavaScript解析器实行分析,而不是一贯解析JSON数据。别的,COLANDS是壹种web浏览器的本领标准,它为web服务器定义了1种格局,从而允许服务器的能源能够被不一致域的网页访问。CO奥迪Q5S被看做是JSONP的最新代替品,并且可以被抱有今世浏览器帮助。由此,不提出接纳JSONP。任何情况下,推荐选取CO牧马人S。

支持CORS

  在服务端实现COBMWX五S一点也不细略,只要求在发送响应时顺便HTTP头,例如: 

Access-Control-Allow-Origin: *

  唯有在多少是国有使用的事态下才会将做客来源设置为”*”。大繁多意况下,Access-Control-Allow-Origin头应该钦点哪些域能够倡导四个CO昂科拉S请求。只有要求跨域访问的UHavalL才设置COPRADOS头。

Access-Control-Allow-Origin: http://example.com:8080
http://foo.example.com

  以上Access-Control-Allow-Origin头中,被设置为只同意受重视的域能够访问。

Access-Control-Allow-Credentials: true

  只在急需时才使用方面这一个header,因为一旦用户已经报到的话,它会同时发送cookies/sessions。

  这几个headers能够通过web服务器、代理来张开配备,可能从服务器本人发送。不推荐在服务端完毕,因为很不灵活。或许,能够选拔方面包车型地铁第两种方法,在web服务器上配置贰个用空格分隔的域的列表。更加多关于CO安德拉S的剧情能够参照那里:http://enable-cors.org/

支持CORS

  在服务端完结CO奥迪Q5S很简单,只要求在出殡和埋葬响应时顺便HTTP头,例如: 

Access-Control-Allow-Origin: *

  唯有在多少是公共使用的情事下才会将访问来源设置为”*”。大诸多场地下,Access-Control-Allow-Origin头应该钦定哪些域能够发起三个COCR-VS请求。惟有须要跨域访问的UPAJEROL才设置COTiguanS头。

Access-Control-Allow-Origin: http://example.com:8080
http://foo.example.com

  以上Access-Control-Allow-Origin头中,棉被服装置为只允许受正视的域能够访问。

Access-Control-Allow-Credentials: true

  只在须求时才使用方面这些header,因为只要用户已经报到的话,它会同时发送cookies/sessions。

  这几个headers可以经过web服务器、代理来进行配备,或许从服务器本人发送。不引入在服务端完结,因为很不灵敏。只怕,能够应用方面包车型地铁第二种办法,在web服务器上安插3个用空格分隔的域的列表。愈来愈多关于CO索罗德S的内容能够参照那里:http://enable-cors.org/

支持JSONP

  JSONP通过应用GET请求避开浏览器的限量,从而实现对富有服务的调用。其行事原理是请求方在央浼的ULANDL上增多三个字符串查询参数(例如:jsonp=”jsonp_callback”),个中“jsonp”参数的值是JavaScript函数名,该函数在有响应重回时将会被调用。

  由于GET请求中从不包括请求体,JSONP在接纳时有着严重的局限性,因而数据必须通过字符串查询参数来传递。同样的,为了支持PUT,POST和DELETE方法,HTTP方法必须也由此字符串查询参数来传递,类似_method=POST这种样式。像那样的HTTP方法传送情势是不引入应用的,那会让服务处于安全危机之中。

  JSONP平时在壹部分不援助COHavalS的老旧浏览器中央银行使,借使要改成协理COLacrosseS的,会影响全体服务器的架构。恐怕大家也得以因而代办来贯彻JSONP。总来讲之,JSONP正在被COGL450S所代表,我们相应尽大概地应用CORAV四S。

  为了在服务端扶助JSONP,在JSONP字符串查询参数字传送递时,响应需求求实践以下那几个操作:

  1. 响应体必须封装成贰个参数字传送递给jsonp中钦赐的JavaScript函数(例如:jsonp_callback(“<JSON
    response body>”))。
  2. 始终重临HTTP状态码200(OK),并且将真实的状况作为JSON响应中的一片段再次回到。

  别的,响应体中时时必须包括响应头。那使得JSONP回调方法须要依据响应体来分明响应处理情势,因为它本人无法得知真实的响应头和情景值。

  上边的例子是遵照上述措施封装的一个回去error状态的jsonp(注意:HTTP的响应状态是200):

jsonp_callback("{'code':'404', 'status':'error','headers':[],'message':'resource XYZ not
found','data':'NotFoundException'}")

  成功成立后的响应类似于那般(HTTP的响应状态仍是200):

jsonp_callback("{'code':'201', 'status':'error','headers':
[{'Location':'http://www.example.com/customers/12345'}],'data':'12345'}")

 

支持JSONP

  JSONP通过使用GET请求避开浏览器的界定,从而完结对具备服务的调用。其行事原理是请求方在呼吁的U奥迪Q5L上增添1个字符串查询参数(例如:jsonp=”jsonp_callback”),当中“jsonp”参数的值是JavaScript函数名,该函数在有响应重回时将会被调用。

  由于GET请求中从不包罗请求体,JSONP在使用时有着严重的局限性,因而数据必须透过字符串查询参数来传递。同样的,为了扶助PUT,POST和DELETE方法,HTTP方法必须也通过字符串查询参数来传递,类似_method=POST那种方式。像这么的HTTP方法传送方式是不推荐使用的,那会让服务处于安全风险之中。

  JSONP平日在有的不援助CO宝马X3S的老旧浏览器中应用,若是要改成辅助CO大切诺基S的,会影响整个服务器的架构。或然我们也足以由此代理来贯彻JSONP。综上说述,JSONP正在被COPAJEROS所取代,大家应有尽或许地行使CO陆风X八S。

  为了在服务端补助JSONP,在JSONP字符串查询参数字传送递时,响应必须求实施以下那些操作:

  1. 响应体必须封装成3个参数字传送递给jsonp中钦点的JavaScript函数(例如:jsonp_callback(“<JSON
    response body>”))。
  2. 始终重回HTTP状态码200(OK),并且将真实的场所作为JSON响应中的一片段重返。

  其余,响应体中时时必须含有响应头。那使得JSONP回调方法要求遵照响应体来规定响应处理形式,因为它自己不能够得知真实的响应头和景观值。

  上面包车型客车事例是根据上述方法封装的一个回来error状态的jsonp(注意:HTTP的响应状态是200):

jsonp_callback("{'code':'404', 'status':'error','headers':[],'message':'resource XYZ not
found','data':'NotFoundException'}")

  成功开创后的响应类似于那样(HTTP的响应状态仍是200):

jsonp_callback("{'code':'201', 'status':'error','headers':
[{'Location':'http://www.example.com/customers/12345'}],'data':'12345'}")

 

查询,过滤和分页

  对于大数据集,从带宽的角度来看,限制再次来到的数据量是尤其重要的。而从UI处理的角度来看,限制数据量也1如既往至关心爱戴要,因为UI平日只可以呈现大数据汇总的一小部分数量。在数据集的增速不明确的意况下,限制私下认可重临的数据量是很有须要的。以推文(Tweet)为例,要拿走某些用户的推文(通过个人主页的命宫轴),假若未有尤其钦点,请求暗中认可只会回来20条记下,纵然系统最多能够回去200条记下。

  除了限制再次来到的数据量,大家还索要思考怎么着对时局据集举行“分页”或下拉滚动操作。创造数量的“页码”,重返大数额列表的已知片段,然后标出数据的“前1页”和“后1页”——这一行为被喻为分页。其它,我们恐怕也必要内定响应大校包蕴怎样字段或性质,从而限制再次来到值的数码,并且大家意在最终能够通过特定值来举行查询操作,并对重临值举行排序。

  有三种首要的秘技来还要限定查询结果和实行分页操作。首先,大家能够建立一个目录方案,它能够以页码为导向(请求中要付出每1页的记录数及页码),也许以记录为导向(请求中央直机关接交给第三条记下和末段一条记下)来明确重回值的起初地方。举个例子,那两种格局分别代表:“给出第6页(若是每页有20条记下)的记录”,或“给出第90到第一20条的笔录”。

  服务端将根据运作体制来张开切分。有个别UI工具,比如Dojo
JSON会选拔模仿HTTP规范行使字节范围。借使服务端帮衬out of
box(即开箱即用效应),则前端UI工具和后端服务中间无需任何转变,那样使用起来会很方便。

  下文将介绍一种方法,既能够帮衬Dojo那样的分页形式(在请求头中提交记录的限定),也能协助采纳字符串查询参数。那样1来服务端将变得越来越灵活,既能够使用类似Dojo同样先进的UI工具集,也得以利用简易直接的链接和标签,而无需再为此增添复杂的费用工作。但万一服务不直接支持UI功用,可以考虑不要在请求头中提交记录范围。

  要专门提议的是,大家并不推荐在装有服务中动用查询、过滤和分页操作。并不是持有能源都暗许扶助这么些操作,唯有少数特定的资源才支撑。服务和财富的文档应当表达什么接口协理那一个扑朔迷离的功能。

查询,过滤和分页

  对于大数据集,从带宽的角度来看,限制重返的数据量是卓殊首要的。而从UI处理的角度来看,限制数据量也同样首要,因为UI平常只好呈现大数量集中的一小部分多少。在数据集的增速不分明的情事下,限制暗中认可再次回到的数据量是很有必要的。以推文(Tweet)为例,要获得有些用户的推文(通过个人主页的年月轴),假诺未有专门钦点,请求暗中认可只会回来20条记下,就算系统最多能够回去200条记下。

  除了限制再次回到的数据量,大家还要求思考什么对命局据集举办“分页”或下拉滚动操作。创造数量的“页码”,重临大数量列表的已知片段,然后标出数据的“前壹页”和“后壹页”——这一表现被称为分页。别的,大家大概也须要钦命响应旅长包括哪些字段或品质,从而限制重返值的数量,并且我们期望最终可以通过一定值来进展询问操作,并对再次来到值举行排序。

  有二种首要的法子来还要限制查询结果和施行分页操作。首先,大家得以建立3个目录方案,它能够以页码为导向(请求中要付出每壹页的记录数及页码),大概以记录为导向(请求中一向交给第三条记下和最后一条记下)来规定重回值的序曲地点。举个例子,那三种办法分别表示:“给出第四页(假使每页有20条记下)的笔录”,或“给出第100到第220条的记录”。

  服务端将依照运作机制来实行切分。有个别UI工具,比如Dojo
JSON会选用模仿HTTP规范使用字节范围。借使服务端帮衬out of
box(即开箱即用效应),则前端UI工具和后端服务时期无需任何调换,这样使用起来会很有益。

  下文将介绍1种办法,既能够匡助Dojo那样的分页格局(在请求头中付出记录的限量),也能支撑选用字符串查询参数。那样一来服务端将变得更灵敏,既能够运用类似Dojo同样先进的UI工具集,也可以动用轻便直接的链接和标签,而无需再为此扩充复杂的开荒工作。但1旦服务不直接援助UI成效,可以设想不要在请求头中付出记录范围。

  要专门建议的是,我们并不推荐在有着服务中选用查询、过滤和分页操作。并不是负有财富都暗中同意帮衬这一个操作,唯有少数特定的能源才支撑。服务和财富的文书档案应当表达怎么着接口协理这几个扑朔迷离的效劳。

结果限制

  “给出第壹到第陆5条的笔录”,那种请求数据的艺术和HTTP的字节范围规范更平等,因而我们可以用它来标志Range
header。而“从第三条记下初阶,给出最多20条记下”这种情势更易于阅读和通晓,因而我们平常会用字符串查询参数的艺术来表示。

  综上所述,推荐既襄助使用HTTP Range
header,也协理使用字符串查询参数——offset(偏移量)和limit(限制),然后在服务端对响应结果开展限定。注意,要是还要帮助那三种艺术,那么字符串查询参数的优先级要高于Range
header。

  那里您只怕会有个问号:“那三种艺术效果相似,可是回到的多寡不完全壹致。那会不会令人歪曲呢?”恩…那是七个难点。首先要应对的是,那确实会令人歪曲。关键是,字符串查询参数看起来更为清晰易懂,在营造和剖析时尤其惠及。而Range
header则越多是由机器来利用(偏向于底层),它进一步契合HTTP使用专业。

  由此可知,解析Range
header的工作会扩充复杂度,相应的客户端在创设请求时也亟需开展局地甩卖。而选择单独的limit和offset参数会愈加便于精通和创设,并且不需求对开拓职员有更多的渴求。

结果限制

  “给出第1到第6伍条的记录”,那种请求数据的方法和HTTP的字节范围规范更平等,由此大家得以用它来标志Range
header。而“从第一条记下开头,给出最多20条记下”这种方法更便于阅读和明白,因此大家不认为奇会用字符串查询参数的格局来代表。

  综上所述,推荐既帮衬使用HTTP Range
header,也协理使用字符串查询参数——offset(偏移量)和limit(限制),然后在服务端对响应结果开始展览限制。注意,要是还要扶助那三种艺术,那么字符串查询参数的预先级要超越Range
header。

  那里您或者会有个难题:“那三种艺术效果相似,不过回到的多寡不完全一致。那会不会令人歪曲呢?”恩…那是三个难点。首先要回答的是,那诚然会让人歪曲。关键是,字符串查询参数看起来更为清晰易懂,在塑造和分析时越发有利于。而Range
header则越来越多是由机械来利用(偏向于底层),它更是符合HTTP使用正式。

  由此可见,解析Range
header的工作会扩展复杂度,相应的客户端在创设请求时也亟需开始展览局地处理。而选择单独的limit和offset参数会进一步轻松理解和营造,并且不要求对开荒人士有更加多的渴求。

用范围标识举办限定

  当用HTTP header而不是字符串查询参数来获得记录的范围时,Ranger
header应该通过以下内容来钦命范围: 

  Range: items=0-24

  注意记录是从0开头的接连字段,HTTP规范中验证了怎么选拔Range
header来请求字节。也正是说,假诺要请求数据汇总的率先条记下,范围应该从0伊始算起。上述的请求将会回来前2几个记录,假如数据汇总至少有二5条记下。

  而在服务端,通过检查请求的Range
header来明确该再次来到哪些记录。只要Range
header存在,就会有二个简约的正则表明式(如”items=(\d+)-(\d+)”)对其开始展览剖析,来获得要物色的范围值。

用范围标识进行限制

  当用HTTP header而不是字符串查询参数来博取记录的限定期,Ranger
header应该经过以下内容来钦定范围: 

  Range: items=0-24

  注意记录是从0起头的连日字段,HTTP规范中证实了哪些选用Range
header来请求字节。也正是说,假诺要乞请数据汇总的首先条记下,范围应该从0早先算起。上述的乞请将会回来前二十六个记录,如若数据集中至少有2伍条记下。

  而在服务端,通过检查请求的Range
header来明确该重回哪些记录。只要Range
header存在,就会有一个大约的正则表明式(如”items=(\d+)-(\d+)”)对其开始展览解析,来收获要搜索的范围值。

用字符串查询参数进行限制

  字符串查询参数被视作Range
header的代替选取,它接纳offset和limit作为参数名,个中offset代表要查询的首先条记下编号(与上述的用来范围标记的items第1个数字一样),limit代表记录的最大条数。上边包车型大巴事例重临的结果与上述用范围标志的例子同样:

  GET http://api.example.com/resources?offset=0&limit=25

  Offset参数的值与Range
header中的类似,也是从0开首计算。Limit参数的值是回来记录的最大数目。当字符串查询参数中未内定limit时,服务端应当交付八个缺省的最大limit值,可是那个参数的使用都须要在文书档案中开始展览表达。

用字符串查询参数进行限制

  字符串查询参数被当作Range
header的替代选拔,它应用offset和limit作为参数名,个中offset代表要询问的首先条记下编号(与上述的用于范围标志的items第3个数字同样),limit代表记录的最大条数。上面包车型客车事例再次来到的结果与上述用范围标识的例子一样:

  GET http://api.example.com/resources?offset=0&limit=25

  Offset参数的值与Range
header中的类似,也是从0开始总计。Limit参数的值是重回记录的最大数量。当字符串查询参数中未钦点limit时,服务端应当交付1个缺省的最大limit值,不过那个参数的利用都亟待在文书档案中开始展览认证。

基于范围的响应

  对2个基于范围的伸手来讲,无论是通过HTTP的Range
header照旧通过字符串查询参数,服务端都应当有2个Content-Range
header来响应,以证明重回记录的条数和总记录数:

  Content-Range: items 0-24/66

  注意那里的总记录数(如本例中的6六)不是从0起首揣度的。如若要呼吁数据集中的末段几条记下,Content-Range
header的内容应该是如此:

  Content-Range: items 40-65/66

  依照HTTP的行业内部,假若响应时总记录数未知或不便计算,也得以用星号(”*”)来顶替(如本例中的6陆)。本例中响应头也可这般写:

  *Content-Range: items 40-65/**

  但是要小心,Dojo或部分别样的UI工具大概不援救该符号。

依照范围的响应

  对二个依照范围的伸手来讲,无论是通过HTTP的Range
header还是经过字符串查询参数,服务端都应当有三个Content-Range
header来响应,以注明再次回到记录的条数和总记录数:

  Content-Range: items 0-24/66

  注意那里的总记录数(如本例中的66)不是从0起首猜想的。尽管要请求数据集中的末尾几条记下,Content-Range
header的内容应当是那般:

  Content-Range: items 40-65/66

  遵照HTTP的行业内部,假若响应时总记录数未知或难以总括,也足以用星号(”*”)来代替(如本例中的6陆)。本例中响应头也可那样写:

  *Content-Range: items 40-65/**

  然而要注意,Dojo或部分任何的UI工具恐怕不协理该符号。

分页

  上述措施通过请求方内定数据集的界定来界定重返结果,从而实现分页效能。下面的事例中计算有66条记下,假设每页二伍条记下,要显得第三页数据,Range
header的始末如下:

  Range: items=25-49

  同样,用字符串查询参数表示如下:

  GET …?offset=25&limit=25

  服务端会相应地回来一组数据,附带的Content-Range header内容如下:

  Content-Range: 25-49/66

  在大部情景下,那种分页格局都没反常。但偶尔会有那种地方,正是要回来的笔录数据不可能直接表示成多少集中的行号。还有正是有些数据集的浮动异常快,不断会有新的多寡插入到数码汇总,那样自然会招致分页出现难点,1些再一次的数量大概会现出在不一样的页中。

  按日期排列的数据集(例如推特(Twitter)feed)正是壹种广泛的情景。纵然你照旧得以对数据开始展览分页,但有时候用”after”或”before”那样的根本字并与Range
header(可能与字符串查询参数offset和limit)同盟来兑现分页,看起来会尤其简洁易懂。

  例如,要博得给定时期戳的前20条评论:

  GET
http://www.example.com/remarks/home\_timeline?after=&lt;timestamp&gt

  Range: items=0-19

  GET
http://www.example.com/remarks/home\_timeline?before=&lt;timestamp&gt

*  Range: items=0-19*

  用字符串查询参数表示为:

  GET
http://www.example.com/remarks/home\_timeline?after=&lt;timestamp&gt;&offset=0&limit=20 

*  GET
http://www.example.com/remarks/home\_timeline?before=&lt;timestamp&gt;&offset=0&limit=20*

  有关在区别景色对时间戳的格式化处理,请参见下文的“日期/时间处理”。

  假诺请求风尚未点名要回去的数额范围,服务端再次回到了一组私下认可数据或限制的最大数据集,那么服务端同时也应有在重临结果中包含Content-Range
header来和客户端举办确认。以地点个人主页的时光轴为例,无论客户端是否钦命了Range
header,服务端每一趟都只回去20条记下。此时,服务端响应的Content-Range
header应该包括如下内容:

  Content-Range: 0-19/4125

  或 *Content-Range: 0-19/**

分页

  上述措施通过请求方钦命数据集的限制来界定再次来到结果,从而完毕分页成效。上边的例子中1共有6六条记下,假诺每页2五条记下,要体现第叁页数据,Range
header的内容如下:

  Range: items=25-49

  同样,用字符串查询参数表示如下:

  GET …?offset=25&limit=25

  服务端会相应地回来1组数据,附带的Content-Range header内容如下:

  Content-Range: 25-49/66

  在大多数动静下,那种分页形式都并未有格外态。但奇迹会有那种景色,正是要重回的笔录数据不可能直接表示成多少集中的行号。还有便是有些数据集的变化非常快,不断会有新的数码插入到多少集中,那样自然会产生分页现身难题,一些再一次的多少可能会产出在差异的页中。

  按日期排列的数据集(例如Twitterfeed)便是1种广泛的情景。尽管您要么得以对数据开始展览分页,但偶尔用”after”或”before”那样的机要字并与Range
header(大概与字符串查询参数offset和limit)同盟来达成分页,看起来会愈加简明易懂。

  例如,要收获给按时间戳的前20条评论:

  GET
http://www.example.com/remarks/home\_timeline?after=&lt;timestamp&gt

  Range: items=0-19

  GET
http://www.example.com/remarks/home\_timeline?before=&lt;timestamp&gt

*  Range: items=0-19*

  用字符串查询参数表示为:

  GET
http://www.example.com/remarks/home\_timeline?after=&lt;timestamp&gt;&offset=0&limit=20 

*  GET
http://www.example.com/remarks/home\_timeline?before=&lt;timestamp&gt;&offset=0&limit=20*

  有关在不相同处境对时间戳的格式化处理,请参见下文的“日期/时间处理”。

  如果请求时未尝点名要回来的多寡范围,服务端重回了一组暗中认可数据或限制的最大数据集,那么服务端同时也相应在回来结果中含有Content-Range
header来和客户端实行确认。以地点个人主页的时光轴为例,无论客户端是否钦点了Range
header,服务端每回都只回去20条记下。此时,服务端响应的Content-Range
header应该包蕴如下内容:

  Content-Range: 0-19/4125

  或 *Content-Range: 0-19/**

结果的过滤和排序

  针对重临结果,还亟需思念怎样在服务端对数据开始展览过滤和排列,以及怎么着按钦定的逐1对子数据开始展览搜寻。这么些操作能够与分页、结果限制,以及字符串查询参数filter和sort等相结合,能够兑现壮大的数据检索作用。

  再重申二次,过滤和排序都以错综复杂的操作,不供给暗中认可提必要持有的财富。下文将介绍怎样能源要求提供过滤和排序。

结果的过滤和排序

  针对再次回到结果,还亟需思考如何在服务端对数码进行过滤和排列,以及如何按钦定的次第对子数据开展查找。这么些操作可以与分页、结果限制,以及字符串查询参数filter和sort等相结合,可以完成庞大的数据检索作用。

  再重申3次,过滤和排序都以扑朔迷离的操作,不要求暗中认可提要求持有的资源。下文将介绍怎样能源须求提供过滤和排序。

过滤

  在本文中,过滤被定义为“通过一定的准绳来分明必须求回去的数额,从而收缩再次回到的数额”。假诺服务端协助1套完整的比较运算符和错综复杂的条件合营,过滤操作将变得一定复杂。然而大家普通会利用部分回顾的表达式,如starts-with(以…开首)或contains(蕴涵)来张开相称,以确定保证重临数据的完整性。

  在大家起始谈论过滤的字符串查询参数从前,必须先清楚为什么要动用单个参数而不是多少个字符串查询参数。从根本上来讲是为着减少参数名称的争执。我们曾经有offsetlimitsort(见下文)参数了。假如只怕的话还会有jsonpformat标志符,也许还会有afterbefore参数,这个都以在本文中关系过的字符串查询参数。字符串查询中利用的参数愈多,就越或许导致参数名称的争辨,而使用单个过滤参数则会将争辩的恐怕降到最低。

  其余,从服务端也很轻易仅通过单个的filter参数来剖断请求方是还是不是必要多少过滤效果。假如查询必要的复杂度扩展,单个参数将更具有灵活性——能够本人建立壹套作用完全的查询语法(详见下文OData注释或访问http://www.odata.org)。

  通过引进一组普及的、公认的分隔符,用于过滤的表明式能够以那多少个直观的款型被使用。用那一个分隔符来设置过滤查询参数的值,这么些分隔符所创设的参数名/值对能够进一步轻巧地棉被和衣服务端解析并加强数据查询的属性。最近已有些分隔符包含用来分隔每一个过滤短语的竖线(”|”)和用来分隔参数名和值的双冒号(”::”)。那套分隔符丰盛唯一,并符合大繁多境况,同时用它来构建的字符串查询参数也越来越便于通晓。上面将用二个轻便的例子来介绍它的用法。尽管我们想要给名字为“托德”的用户们发送请求,他们住在塔林,有着“Grand
Poobah”之称。用字符串查询参数达成的伸手UEscortI如下:

  GET
http://www.example.com/users?filter="name::todd|city::denver|title::grand
poobah”

  双冒号(”::”)分隔符将属性名和值分开,那样属性值就可见包括空格——服务端能更易于地从属性值中剖析出分隔符。

  注意查询参数名/值对中的属性名要和服务端再次回到的品质名相相配。

  轻松而有效。有关大小写敏感的难题,要基于具体意况来看,但总的来说,在毫不关注大小写的意况下,过滤效果能够很好地运营。若查询参数名/值对中的属性值未知,你也得以用星号(”*”)来代替。

  除了简单的表明式和通配符之外,若要进行更复杂的查询,你必须求引进运算符。在那种景观下,运算符自身也是属性值的1部分,能够棉被和衣服务端解析,而不是形成属性名的1某些。当须要复杂的query-language-style(查询语言风格)成效时,可参考Open
Data Protocol (OData) Filter System Query
Option表达中的查询概念(详见http://www.odata.org/documentation/uriconventions#FilterSystemQueryOption)。

过滤

  在本文中,过滤被定义为“通过特定的原则来规定必须求赶回的多寡,从而收缩再次回到的数据”。如果服务端帮忙一套完整的可比运算符和复杂性的标准化相当,过滤操作将变得分外复杂。可是大家日常会采取壹些大约的表明式,如starts-with(以…起头)或contains(包涵)来展开相称,以担保重返数据的完整性。

  在大家早先谈论过滤的字符串查询参数在此以前,必须先清楚为什么要动用单个参数而不是八个字符串查询参数。从根本上来说是为着收缩参数名称的争持。大家曾经有offsetlimitsort(见下文)参数了。即使或许的话还会有jsonpformat标志符,或者还会有afterbefore参数,那些都是在本文中关系过的字符串查询参数。字符串查询中利用的参数越多,就越或者引致参数名称的争辩,而使用单个过滤参数则会将冲突的只怕降到最低。

  其余,从服务端也很轻松仅通过单个的filter参数来判别请求方是还是不是须要多少过滤效果。假诺查询必要的复杂度扩大,单个参数将更有着灵活性——能够本身树立一套功用完全的查询语法(详见下文OData注释或访问http://www.odata.org)。

  通过引进一组广泛的、公认的分隔符,用于过滤的表明式能够以尤其直观的款型被利用。用那一个分隔符来设置过滤查询参数的值,这个分隔符所创造的参数名/值对能够进一步便于地棉被和衣服务端解析并巩固多少查询的属性。近来已有个别分隔符包含用来分隔种种过滤短语的竖线(”|”)和用来分隔参数名和值的双冒号(”::”)。那套分隔符丰硕唯壹,并符合大多数动静,同时用它来营造的字符串查询参数也愈发便于驾驭。上面将用3个总结的事例来介绍它的用法。假诺大家想要给名叫“托德”的用户们发送请求,他们住在圣Jose,有着“Grand
Poobah”之称。用字符串查询参数完成的伏乞UXC90I如下:

  GET
http://www.example.com/users?filter="name::todd|city::denver|title::grand
poobah”

  双冒号(”::”)分隔符将属性名和值分开,那样属性值就可以包罗空格——服务端能更便于地从属性值中分析出分隔符。

  注意查询参数名/值对中的属性名要和服务端重回的性子名相相配。

  简单而卓有功能。有关大小写敏感的主题材料,要依照具体情形来看,但总的看,在毫无关怀大小写的意况下,过滤效果能够很好地运营。若查询参数名/值对中的属性值未知,你也足以用星号(”*”)来代替。

  除了轻松的表明式和通配符之外,若要实行更复杂的查询,你不能够不要引进运算符。在那种景况下,运算符自身也是属性值的1某些,能够棉被和衣服务端解析,而不是成为属性名的一有的。当要求复杂的query-language-style(查询语言风格)效用时,可参考Open
Data Protocol (OData) Filter System Query
Option表明中的查询概念(详见http://www.odata.org/documentation/uriconventions#FilterSystemQueryOption)。

排序

  排序决定了从服务端重返的记录的逐条。也正是对响应中的多条记下进行排序。

  一样,大家那里只思索部分相比较轻易的情况。推荐使用排序字符串查询参数,它包涵了壹组用分隔符分隔的属性名。具体做法是,暗中认可对种种属性名按升序排列,如若属性名有前缀”-“,则按降序排列。用竖线(”|”)分隔每一种属性名,那和日前过滤效果中的参数名/值对的做法无差距于。

  举个例子,如若大家想按用户的姓和名张开升序排序,而对雇佣时间开始展览降序排序,请求将是那般的:

  GET
http://www.example.com/users?sort=last\_name|first\_name|-hire\_date

  再度强调一下,查询参数名/值对中的属性名要和服务端重临的属性名相相配。别的,由于排序操作相比较复杂,大家只对要求的财富提供排序作用。假使须要的话也得以在客户端对小的能源集合进行排列。

 

排序

  排序决定了从服务端再次来到的记录的各样。也正是对响应中的多条记下实行排序。

  一样,大家那边只考虑部分比较轻易的事态。推荐应用排序字符串查询参数,它包涵了1组用分隔符分隔的属性名。具体做法是,默许对各个属性名按升序排列,假设属性名有前缀”-“,则按降序排列。用竖线(”|”)分隔每一个属性名,那和日前过滤效果中的参数名/值对的做法同样。

  举个例证,要是大家想按用户的姓和名实行升序排序,而对雇佣时间展开降序排序,请求将是如此的:

  GET
http://www.example.com/users?sort=last\_name|first\_name|-hire\_date

  再一次重申一下,查询参数名/值对中的属性名要和服务端再次回到的本性名相相配。此外,由于排序操作相比较复杂,大家只对急需的财富提供排序作用。如若需求的话也足以在客户端对小的财富集合举行排列。

 

劳动版本管理

   坦率地讲,壹谈起版本就会令人认为很不便,很麻烦,不太轻便,甚至会令人觉着优伤——因为那会增多API的复杂度,并还要大概会对客户端产生壹些震慑。因而,在API的统筹中要尽量制止五个不等的版本。

  不支持版本,不将版本调控作为不佳的API设计的信赖。借使你在APIs的筹划中引进版本,这迟早都会让你抓狂。由于再次来到的数额经过JSON来显现,客户端会由于不一致的本子而接受到不一样的属性。那样就会设有部分主题素材,如从内容本人和表明规则方面改动了2个已存在的习性的意义。

  当然,我们不可能制止API只怕在某个时候供给转移重回数据的格式和剧情,而那也将招致消费端的一部分变化,大家理应防止举办一些根本的调动。将API进行版本化管理是制止那种重大转变的一种有效措施。

劳务版本管理

   坦率地讲,壹谈起版本就会令人觉着很不方便,很麻烦,不太轻巧,甚至会令人以为难过——因为那会追加API的复杂度,并同时只怕会对客户端发生部分震慑。因而,在API的统一筹划中要尽量防止三个不等的本子。

  不支持版本,不将版本调控作为不佳的API设计的依靠。如若你在APIs的安排性中引进版本,那迟早都会让你抓狂。由于再次回到的数额经过JSON来显示,客户端会由于分化的版本而接受到不一致的属性。这样就会存在有的标题,如从内容小编和认证规则方面改变了叁个已存在的习性的意义。

  当然,大家鞭长莫及幸免API大概在少数时候须求更换再次回到数据的格式和内容,而那也将促成消费端的1些变迁,我们理应制止实香港行政局地要害的调控。将API举行版本化管理是幸免那种首要变动的1种有效情势。

因而剧情协商帮衬版本管理

  以后,版本管理通过UHummerH贰I本身的版本号来成功,客户端在呼吁的UQashqaiI中标明要获得的财富的版本号。事实上,大多大集团如推特、Yammer、推特(Twitter)、谷歌(Google)等日常在他们的U奥迪Q7I里使用版本号。甚至像WSO2那样的API管理工科具也会在它的U劲客Ls中要求版本号。

  面向REST原则,版本管理技艺飞速发展。因为它不带有HTTP规范中放置的header,也不帮助仅当一个新的财富或概念被引进时才应该增多新ULX570I的见解——即版本不是表现格局的变化。另1人歌唱会对台戏的理由是财富URI是不会随时间退换的,财富正是财富。

  U奥迪Q三I应该能大约地辨别能源——而不是它的“形状”(状态)。另贰个就是必须钦命响应的格式(表征)。还有一些HTTP
headers:Accept 和 Content-Type。Accept
header允许客户端内定所期待或能支撑的响应的传播媒介类型(一种或多样)。Content-Type
header可分别被客户端和服务端用来钦命请求或响应的数量格式。

  例如,要收获一个user的JSON格式的多寡:

  #Request:

  GET http://api.example.com/users/12345
  Accept: application/json; version=1

  #Response:

  HTTP/1.1 200 OK
  Content-Type: application/json; version=1

  {“id”:”12345″, “name”:”Joe DiMaggio”}

  现在,我们对同1财富请求版本二的数额:

  #Request:

  GET http://api.example.com/users/12345
  Accept: application/json; version=2

  #Response:

  HTTP/1.1 200 OK
  Content-Type: application/json; version=2

  {“id”:”12345″, “firstName”:”Joe”, “lastName”:”DiMaggio”}

  Accept
header被用来代表所企望的响应格式(以及示例中的版本号),注意上述八个同样的UXC60I是怎么产生在不一致的版本中分辨能源的。也许,借使客户端供给1个XML格式的数量,可以将Accept
header设置为”application/xml”,假使供给的话也能够带多少个钦赐的版本号。

  由于Accept
header能够棉被服装置为允许各样媒体类型,在响应请求时,服务器将把响应的Content-Type
header设置为最相配客户端请求内容的档次。更多新闻能够参见http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.Html

  例如:

  #Request

  GET http://api.example.com/users/12345

  Accept: application/json; version=1, application/xml; version=1

  上述呼吁中,要是服务器支持JSON
和XML格式的请求,也许三种都接济,那么将由服务器来调整最终回到哪类档次的数码。但不论是服务器选取哪1种,都会在响应中带有Content-Type
header。

  例如,假若服务器再次来到application/xml格式的数额,结果是:

  #Response

  HTTP/1.1 200 OK
  Content-Type: application/xml; version=1

  <user>
    <id>12345</id>
    <name>Joe DiMaggio</name>
  </user>

  为了印证Content-Type在发送数据给服务器时的用处,那里给出2个用JSON格式创造新用户的例证:

  #Request

  POST http://api.example.com/users
  Content-Type: application/json;version=1

  {“name”:”Marco Polo”}

  可能,调用版本二的接口:

  #Request

  POST http://api.example.com/users
  Content-Type: application/json;version=2

  {“firstName”:”Marco”, “lastName”:”Polo”}

因此剧情协商补助版本管理

  现在,版本管理通过U帕杰罗I本身的本子号来达成,客户端在呼吁的URAV4I中标明要获得的能源的版本号。事实上,多数大公司如Twitter、Yammer、Instagram(TWTRAV4.US)、谷歌(Google)等不时在他们的U昂科雷I里使用版本号。甚至像WSO2那样的API管理工具也会在它的U奥迪Q5Ls中要求版本号。

  面向REST原则,版本管理能力火速发展。因为它不蕴含HTTP规范中置放的header,也不帮助仅当2个新的财富或概念被引进时才应该增添新UCR-VI的视角——即版本不是表现情势的变迁。另一个反对的说辞是能源U福特ExplorerI是不会随时间改换的,能源正是能源。

  ULANDI应该能简单地辨别能源——而不是它的“形状”(状态)。另1个正是必须钦定响应的格式(表征)。还有部分HTTP
headers:Accept 和 Content-Type。Accept
header允许客户端钦定所愿意或能支撑的响应的媒体类型(1种或二种)。Content-Type
header可分别被客户端和服务端用来钦定请求或响应的数额格式。

  例如,要获得3个user的JSON格式的数目:

  #Request:

  GET http://api.example.com/users/12345
  Accept: application/json; version=1

  #Response:

  HTTP/1.1 200 OK
  Content-Type: application/json; version=1

  {“id”:”12345″, “name”:”Joe DiMaggio”}

  今后,我们对同样财富请求版本二的多寡:

  #Request:

  GET http://api.example.com/users/12345
  Accept: application/json; version=2

  #Response:

  HTTP/1.1 200 OK
  Content-Type: application/json; version=2

  {“id”:”12345″, “firstName”:”Joe”, “lastName”:”DiMaggio”}

  Accept
header被用来表示所期待的响应格式(以及示例中的版本号),注意上述八个一律的UBMWX3I是何等实今后分化的版本中分辨财富的。或许,假诺客户端要求一个XML格式的数量,能够将Accept
header设置为”application/xml”,假诺需求的话也能够带三个钦赐的版本号。

  由于Accept
header能够被安装为允许两种媒体类型,在响应请求时,服务器将把响应的Content-Type
header设置为最相称客户端请求内容的品种。越多新闻能够参见http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.Html

  例如:

  #Request

  GET http://api.example.com/users/12345

  Accept: application/json; version=1, application/xml; version=1

  上述呼吁中,假如服务器援助JSON
和XML格式的乞请,也许两种都补助,那么将由服务器来调控最后回到哪类档次的多寡。但随便服务器选拔哪一类,都会在响应中涵盖Content-Type
header。

  例如,假设服务器再次回到application/xml格式的数额,结果是:

  #Response

  HTTP/1.1 200 OK
  Content-Type: application/xml; version=1

  <user>
    <id>12345</id>
    <name>Joe DiMaggio</name>
  </user>

  为了证实Content-Type在发送数据给服务器时的用处,那里给出3个用JSON格式成立新用户的例子:

  #Request

  POST http://api.example.com/users
  Content-Type: application/json;version=1

  {“name”:”Marco Polo”}

  或许,调用版本2的接口:

  #Request

  POST http://api.example.com/users
  Content-Type: application/json;version=2

  {“firstName”:”Marco”, “lastName”:”Polo”}

当未有点名版本时,重临什么版本?

  并不必要在每贰个伸手中都内定版本号。由于HTTP
content-negotiation(内容协商)服从类型的“最棒相配”情势,所以您的API也理应根据那点。依照这一尺度,当客户端从未点名版本时,API应当重返所支撑的最早版本。

  依然这几个例子,获取二个user的JSON格式的数额:

  #Request

  GET http://api.example.com/users/12345
  Accept: application/json

  #Response

  HTTP/1.1 200 OK
  Content-Type: application/json; version=1

  {“id”:”12345″, “name”:”Joe DiMaggio”}

  相应地,当以POST方式向服务器发送数据时,要是服务器扶助三个不等版本,而请求时又从未点名版本,和方面包车型大巴例子一样——服务器会将小小/最早版本的数据包涵在body中。为了实行表达,上面包车型大巴例证以JSON格式请求三个富含多版本财富的服务器,来成立2个新用户(预期会回来版本①):

  #Request

  POST http://api.example.com/users
  Content-Type: application/json

  {“name”:”Marco Polo”}

  #Response

  HTTP/1.1 201 OK
  Content-Type: application/json; version=1
  Location: http://api.example.com/users/12345

  {“id”:”12345″, “name”:”Marco Polo”}

当未有点名版本时,重回什么版本?

  并不须要在每三个伸手中都钦赐版本号。由于HTTP
content-negotiation(内容协商)遵循类型的“最佳相配”情势,所以您的API也应有依据那或多或少。依照这1尺码,当客户端从未点名版本时,API应当再次回到所支撑的最早版本。

  如故那个例子,获取1个user的JSON格式的数量:

  #Request

  GET http://api.example.com/users/12345
  Accept: application/json

  #Response

  HTTP/1.1 200 OK
  Content-Type: application/json; version=1

  {“id”:”12345″, “name”:”Joe DiMaggio”}

  相应地,当以POST格局向服务器发送数据时,假如服务器帮忙七个不一样版本,而请求时又尚未点名版本,和地方的例证一样——服务器会将小小/最早版本的数码包括在body中。为了进行验证,上面包车型客车例证以JSON格式请求八个分包多版本能源的服务器,来创制三个新用户(预期会回到版本一):

  #Request

  POST http://api.example.com/users
  Content-Type: application/json

  {“name”:”Marco Polo”}

  #Response

  HTTP/1.1 201 OK
  Content-Type: application/json; version=1
  Location: http://api.example.com/users/12345

  {“id”:”12345″, “name”:”Marco Polo”}

呼吁不援助的本子

  当呼吁1个不帮助的版本号时(包罗在API生命周期中壹度一去不归的能源版本),API应当重临一个荒谬的HTTP状态码406(表示不被接受)。别的,API还应该再次回到二个富含Content-Type:
application/json的响应体,个中包含七个JSON数组,用于申明该服务器支持的档次。

  #Request

  GET http://api.example.com/users/12345
  Content-Type: application/json; version=999

  #Response

  HTTP/1.1 406 NOT ACCEPTABLE 

  Content-Type: application/json

  [“application/json; version=1”, “application/json; version=2”,
“application/xml; version=1”, “application/xml; version=2”]

伸手不支持的本子

  当呼吁1个不支持的本子号时(包蕴在API生命周期中已经一去不复返的财富版本),API应当重回2个谬误的HTTP状态码40陆(表示不被接受)。别的,API还应该再次回到三个分包Content-Type:
application/json的响应体,当中包蕴3个JSON数组,用于表明该服务器帮忙的花色。

  #Request

  GET http://api.example.com/users/12345
  Content-Type: application/json; version=999

  #Response

  HTTP/1.1 406 NOT ACCEPTABLE 

  Content-Type: application/json

  [“application/json; version=1”, “application/json; version=2”,
“application/xml; version=1”, “application/xml; version=2”]

什么样时候应该创制贰个新本子?

  API开垦中的繁多方面都会打破约定,并最终对客户端发生壹些不良影响。假设你不分明API的更换会带来怎样的结果,有限支撑起见最佳思量动用版本调节。当你在考虑提供贰个新本子是不是确切时,只怕挂念对现成的归来表征举办修改是不是分明能满意急需并被客户端所承受时,有那样多少个因素要怀恋。

哪一天应该创造三个新本子?

  API开荒中的多数方面都会打破约定,并最后对客户端爆发局地不良影响。假使您不明确API的更动会带来什么的结局,保证起见最棒思考采取版本调节。当您在考虑提供一个新本子是还是不是妥帖时,或许思量对现存的回到表征举行改造是不是肯定能满足急需并被客户端所接受时,有诸如此类多少个要素要思量。

破坏性的修改

  • 更改属性名(例如将”name”改成”firstName”)
  • 除去属性
  • 改造属性的数据类型(例如将numeric变为string,
    boolean变为bit/numeric,string 变为 datetime等等)
  • 改变验证规则
  • 在Atom样式的链接中,修改”rel”的值
  • 在存活的工作流中引进要求财富
  • 变动财富的概念/意图;概念/意图或能源气象的含义不一致于它原本的意义。例如:
    • 二个content
      type是text/html的能源,以前表示的是有所支持的媒体类型的3个”links”集合,而新的text/html则意味的是用户输入的“web浏览器表单”。
    • 八个富含”endTime”参数的API,对财富”…/users/{id}/exams/{id}”表明的意思是学员在老大时刻付诸试卷,而新的意义则是考试的约定完结时间。
  • 因而增添新的字段来退换现成的财富。将多个能源统壹为三个并弃用原始的能源。
    • 有如此多个财富”…/users/{id}/dropboxBaskets/{id}/messages/{id}”和”…/users/{id}/dropboxBaskets/{id}/messages/{id}/readStatus”。新供给是把readStatus能源的习性放到单独的message能源中,并弃用readStatus财富。那将促成messages能源中指向readStatus能源的链接被移除。

  即便上边列出的并不周详,但它交给了有的会对客户端发生破坏性影响的变通类型,那时急需考虑提供1个新财富或新本子。

破坏性的修改

  • 转移属性名(例如将”name”改成”firstName”)
  • 删去属性
  • 转移属性的数据类型(例如将numeric变为string,
    boolean变为bit/numeric,string 变为 datetime等等)
  • 更换验证规则
  • 在Atom样式的链接中,修改”rel”的值
  • 在现成的工作流中引进需求财富
  • 变动财富的概念/意图;概念/意图或财富情形的意思差别于它原有的意思。例如:
    • 一个content
      type是text/html的能源,在此以前表示的是享有支持的媒体类型的二个”links”集合,而新的text/html则意味的是用户输入的“web浏览器表单”。
    • 一个含有”endTime”参数的API,对财富”…/users/{id}/exams/{id}”表明的含义是学生在那一个时间付诸试卷,而新的含义则是侦查的预定完结时间。
  • 透过丰盛新的字段来改造现成的能源。将多个财富集合为三个并弃用原来的能源。
    • 有诸如此类七个财富”…/users/{id}/dropboxBaskets/{id}/messages/{id}”和”…/users/{id}/dropboxBaskets/{id}/messages/{id}/readStatus”。新须求是把readStatus能源的质量放到单独的message财富中,并弃用readStatus财富。那将促成messages财富中指向readStatus财富的链接被移除。

  尽管上边列出的并不全面,但它交给了1部分会对客户端发生破坏性影响的变通类型,那时急需思虑提供四个新能源或新本子。

非破坏性的改变

  • 在重临的JSON中加多新属性
  • 加上指向任何能源的”link”
  • 增加content-type帮忙的新格式
  • 增加content-language援助的新格式
  • 鉴于API的创造者和买主都要拍卖分化的casing,由此casing的变迁无关首要

非破坏性的修改

  • 在回去的JSON中增添新属性
  • 拉长指向任何财富的”link”
  • 加多content-type支持的新格式
  • 增加content-language补助的新格式
  • 出于API的主要创笔者和顾客都要处理差异的casing,由此casing的扭转毫无干系主要

版本调控应在怎么品级现身?

  提出对单个的财富开始展览版本调控。对API的1对改成,如修改职业流,可能要跨多个财富的版本调控,以此来防守对客户端产生破坏性的影响。

版本调控应在什么等级出现?

  建议对单个的能源开始展览版本调整。对API的部分更改,如修改职业流,可能要跨两个能源的版本调控,以此来幸免对客户端发生破坏性的熏陶。

行使Content-Location来拉长响应

  可选。见TiguanDF(Resource Description Framework,即能源描述框架)规范。

应用Content-Location来拉长响应

  可选。见大切诺基DF(Resource Description Framework,即财富描述框架)规范。

带有Content-Type的链接

  Atom风格的链接扶助”type”属性。提供丰盛的音信以便客户端能够对一定的本子和剧情类型进行调用。

带有Content-Type的链接

  Atom风格的链接援救”type”属性。提供丰裕的新闻以便客户端能够对一定的本子和剧情类型实行调用。

寻觅援救的版本

寻觅帮助的版本

自己应该而且援救几个版本?

  维护五个不一样的版本会让职业变得繁琐、复杂、轻便出错,而且代价高,对于其余给定的能源,你应有帮衬不超越三个本子。

小编应该而且辅助几个本子?

  维护八个不等的版本会让工作变得繁琐、复杂、轻易出错,而且代价高,对于别的给定的财富,你应当支持不超越三个本子。

弃用

  Deprecated(弃用)的指标是用来讲明能源对API还是可用,但在以往会不设有并变得不可用。只顾:弃用的时间长度将由弃用政策决定——那里并从未交给定义。

弃用

  Deprecated(弃用)的指标是用来评释能源对API依旧可用,但在现在会不设有并变得不可用。留意:弃用的时间长度将由弃用政策决定——那里并从未付诸定义。

作者哪些告知客户端被弃用的财富?

  大多客户端以后走访的财富恐怕在新本子引进后会被放弃掉,因而,他们需求有1种格局来发现和监督他们的应用程序对弃用财富的施用。当呼吁多个弃用财富时,API应该健康响应,并含有2个布尔类型的自定义Header
“Deprecated”。以下用三个事例来张开认证。

  #Request

  GET http://api.example.com/users/12345
  Accept: application/json
  Content-Type: application/json; version=1

  #Response

  HTTP/1.1 200 OK
  Content-Type: application/json; version=1
  Deprecated: true
  {“id”:”12345”, “name”:”Joe DiMaggio”}

 

自个儿如何告知客户端被弃用的能源?

  很多客户端以往拜会的能源或者在新本子引入后会被舍弃掉,因而,他们须求有1种艺术来发现和监督他们的应用程序对弃用能源的施用。当呼吁叁个弃用能源时,API应该平常响应,并蕴藏一个布尔类型的自定义Header
“Deprecated”。以下用2个例子来开始展览表明。

  #Request

  GET http://api.example.com/users/12345
  Accept: application/json
  Content-Type: application/json; version=1

  #Response

  HTTP/1.1 200 OK
  Content-Type: application/json; version=1
  Deprecated: true
  {“id”:”12345”, “name”:”Joe DiMaggio”}

 

日子/时间处理

  假诺未有安妥地、一致地处理好日期和时间以来,这将变为三个大麻烦。我们平时会赶过时区的标题,而且由于日期在JSON中是以字符串的格式存在的,要是未钦定统1的格式,那么解析日期也会是3个主题材料。

  在接口内部,服务端应该以UTC或奇霉素T时间来存款和储蓄、处理和缓存时间戳。这将实用消除日期和时间的难点。

日期/时间处理

  如若未有稳妥地、1致地拍卖好日期和岁月的话,那将改为三个大麻烦。大家平时会遭逢时区的主题材料,而且由于日期在JSON中是以字符串的格式存在的,若是未钦点统1的格式,那么解析日期也会是二个标题。

  在接口内部,服务端应该以UTC或维生霉素T时间来囤积、处理和缓存时间戳。那将使得化解日期和岁月的主题材料。

Body内容中的日期/时间连串化

  有四个粗略的法子能够化解这个标题——在字符串中一向用同壹的格式,包含时间片(带有时区新闻)。ISO860一时间格式是3个不易的消除方案,它使用了截然加强的年华格式,包蕴小时、分钟、秒以及秒的小数部分(例如yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)。提议在REST服务的body内容中(请求和响应均蕴含)使用ISO860一代表全数的日期格式。

  顺便提一下,对于那二个基于JAVA的劳动以来,Date艾达pterJ库使用DateAdapter,Iso860壹TimepointAdapter和HttpHeaderTimestampAdapter类可以万分轻松地剖析和格式化ISO860三20日期和时间,以及HTTP
1.壹header(哈弗FC11二3)格式。能够从https://github.com/tfredrich/DateAdapterJ下载。

  对于那么些成立基于浏览器的用户分界面来说,ECMAScript五专业一发轫就带有了JavaScript解析和创办ISO86031日期的始末,所以它应有成为咱们所说的主流浏览器所遵从的章程。当然,固然你要协理这个无法自动解析日期的旧版浏览器,可以行使JavaStript库或正则表明式。那里有多少个能够分析和创办ISO8601时间的JavaStript库:

  http://momentjs.com/

  http://www.datejs.com/

Body内容中的日期/时间类别化

  有贰个总结的艺术能够缓解那么些难点——在字符串中始终用同1的格式,包涵时间片(带有时区新闻)。ISO860一时间格式是一个科学的化解方案,它使用了一心加强的时刻格式,蕴涵小时、分钟、秒以及秒的小数部分(例如yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)。提议在REST服务的body内容中(请求和响应均包蕴)使用ISO860壹代表全数的日期格式。

  顺便提一下,对于那3个基于JAVA的劳动以来,DateAdapterJ库使用DateAdapter,Iso860壹TimepointAdapter和HttpHeaderTimestamp艾达pter类能够卓殊轻便地剖析和格式化ISO8601三日期和时间,以及HTTP
一.1header(XC90FC11二三)格式。能够从https://github.com/tfredrich/DateAdapterJ下载。

  对于这一个制造基于浏览器的用户分界面来讲,ECMAScript5正经壹早先就带有了JavaScript解析和创设ISO86017日期的始末,所以它应该成为大家所说的主流浏览器所遵从的办法。当然,要是你要支持那几个无法自动解析日期的旧版浏览器,能够行使JavaStript库或正则表明式。那里有多少个能够分析和创办ISO860一时间的JavaStript库:

  http://momentjs.com/

  http://www.datejs.com/

HTTP Headers中的日期/时间系列化

  可是上述提出仅适用于HTTP请求或响应内容中的JSON和XML内容,HTTP规范针对HTTP
headers使用另壹种不一致的格式。在被大切诺基FC112三更替的安德拉FC82第22中学提议,该格式包涵了各个日期、时间和date-time格式。可是,提议始终使用时间戳格式,在你的request
headers中它看起来像这么:

  Sun, 06 Nov 1994 08:49:37 GMT

  不过,那种格式未有思虑皮秒只怕秒的拾进制小数。Java的SimpleDataFormat的格式串是:”EEE,
dd MMM yyyy HH:mm:ss ‘创新霉素T'”。

 

HTTP Headers中的日期/时间体系化

  不过上述提议仅适用于HTTP请求或响应内容中的JSON和XML内容,HTTP规范针对HTTP
headers使用另一种分歧的格式。在被科雷傲FC11二三更替的中华VFC82第22中学提出,该格式包括了各个日期、时间和date-time格式。可是,建议始终使用时间戳格式,在您的request
headers中它看起来像那样:

  Sun, 06 Nov 1994 08:49:37 GMT

  然而,这种格式未有思量纳秒恐怕秒的十进制小数。Java的SimpleDataFormat的格式串是:”EEE,
dd MMM yyyy HH:mm:ss ‘庆大霉素T'”。

 

保安服务的中卫

  Authentication(身份注明)指的是认同给定的央求是从服务已知的某人(或某些系统)发出的,且请求者是他协调所注解的拾叁分人。Authentication是为了表明请求者的实事求是身份,而authorization(授权)是为了证实请求者有权力去实践被呼吁的操作。

  本质上,那么些进程是这么的:

  1. 客户端发起1个请求,将authentication的token(身份验证令牌)包括在X-Authentication
    header中,或者将token外加在呼吁的查询串参数中。
  2. 服务器对authorization
    token(授权令牌)进行检讨,并进行验证(有效且未过期),并根据令牌内容分析大概加载认证中央。
  3. 服务器调用授权服务,提供验证中央、被呼吁能源和须求的操作许可。
  4. 只要授权通过了,服务器将会继续健康运作。

  上面第二步的支出可能会相比较大,不过假设尽管存在三个可缓存的权能决定列表(ACL),那么在发生远程请求前,能够在本土成立三个授权客户端来缓存最新的ACLs。

保卫安全服务的安全

  Authentication(身份认证)指的是认可给定的伸手是从服务已知的某人(或有个别系统)发出的,且请求者是她自身所评释的充足人。Authentication是为着表明请求者的实际身份,而authorization(授权)是为了证实请求者有权力去奉行被呼吁的操作。

  本质上,这么些进程是这么的:

  1. 客户端发起1个呼吁,将authentication的token(身份认证令牌)包涵在X-Authentication
    header中,或者将token叠加在伸手的查询串参数中。
  2. 服务器对authorization
    token(授权令牌)实行自笔者批评,并进行验证(有效且未过期),并依照令牌内容分析也许加载认证核心。
  3. 服务器调用授权服务,提供验证中央、被呼吁财富和要求的操作许可。
  4. 如果授权通过了,服务器将会继续健康运维。

  下边第一步的开支或许会比较大,可是壹旦借使存在两个可缓存的权柄决定列表(ACL),那么在产生远程请求前,可以在地面成立一个授权客户端来缓存最新的ACLs。

身份验证

  近期最佳的做法是使用OAuth身份验证。强烈推荐OAuth二,不过它依然居于草案情形。大概采用OAuth1,它完全能够胜任。在一些情况下也得以选用三-Legged
OAuth。越多关于OAuth的正儿八经能够查看那里http://oauth.net/documentation/spec/

  OpenID是2个外加接纳。但是提出将OpenID作为2个附加的身份验证选项,以OAuth为主。更加多关于OpenID的标准能够查看那里http://openid.net/developers/specs/

身份验证

  近日最佳的做法是采纳OAuth身份验证。强烈推荐OAuth2,可是它依旧处于草案情形。大概选拔OAuth1,它完全可以胜任。在一些景况下也能够挑选三-Legged
OAuth。愈多关于OAuth的专业能够查看这里http://oauth.net/documentation/spec/

  OpenID是一个外加选拔。然则提出将OpenID作为贰个附加的身份验证选项,以OAuth为主。更加多关于OpenID的正经能够查看那里http://openid.net/developers/specs/

传输安全

  全数的辨证都应该利用SSL。OAuth2须要授权服务器和access
token(访问令牌)来采纳TLS(安全传输层协议)。

  在HTTP和HTTPS之间切换会带来安全隐患,最棒的做法是具备简报暗中同意都使用TLS。

传输安全

  全数的表达都应当利用SSL。OAuth2要求授权服务器和access
token(访问令牌)来行使TLS(安全传输层协议)。

  在HTTP和HTTPS之间切换会带来安全隐患,最佳的做法是富有简报私下认可都利用TLS。

授权

  对劳动的授权和对其它应用程序的授权一样,未有别的分化。它依照那样3个难点:“主体是或不是对给定的资源有请求的许可?”那里给出了简易的三项数据(主体,能源和许可),由此很轻便构造八个协理那种概念的授权服务。在那之中大旨是被予以能源访问许可的人或系统。使用这个相似概念,就足感到每一个大旨创设2个缓存访问调节列表(ALC)。

授权

  对劳务的授权和对其余应用程序的授权同样,未有其余分化。它根据那样三个难点:“主体是或不是对给定的资源有请求的许可?”那里给出了回顾的三项数据(主体,财富和许可),因而很轻易构造三个援助那种概念的授权服务。个中宗旨是被赋予能源访问许可的人或系统。使用这一个相似概念,就足感觉每1个大旨构建三个缓存访问调节列表(ALC)。

应用程序安全

  对RESTful服务以来,开垦2个平安的web应用适用同样的条件。

  • 在服务器上证实全体输入。接受“已知”的科学的输入并驳回错误的输入。
  • 防止SQL和NoSQL注入。
  • 应用library如微软的Anti-XSS或OWASP的Anti萨姆my来对输出的数量举办编码。
  • 将信息的尺寸限制在规定的字段长度内。
  • 服务应该只展现壹般的错误新闻。
  • 设想工作逻辑攻击。例如,攻击者可以跳过多步骤的预购流程来预定产品而无需输入信用卡新闻呢?
  • 对思疑的活动记录日志。

  RESTful安全须求专注的地点:

  • 注脚数据的JSON和XML格式。
  • HTTP动词应该被界定在同意的形式中。例如,GET请求不能够去除3个实体。GET用来读取实体而DELETE用来删除实体。
  • 专注race
    conditions(竞争条件——由于多个只怕多少个进程竞争使用不可能被同时做客的财富,使得这个经过有一点都不小可能率因为时间上有助于的主次原因此产出难题)。

  API网关可用于监视、限制和调整对API的拜访。以下内容可由网关或RESTful服务实现。

  • 蹲点API的运用情形,并了然怎么着活动是健康的,哪些是非平常的。
  • 范围API的利用,使恶意用户无法停掉贰个API服务(DOS攻击),并且有技艺阻止恶意的IP地址。
  • 将API密钥存款和储蓄在加密的安全密钥库中。

 

应用程序安全

  对RESTful服务以来,开荒2个资阳的web应用适用同样的原则。

  • 在服务器上证实全体输入。接受“已知”的不利的输入并拒绝错误的输入。
  • 防止SQL和NoSQL注入。
  • 采纳library如微软的Anti-XSS或OWASP的Anti萨姆my来对输出的数目举行编码。
  • 将消息的长度限制在规定的字段长度内。
  • 劳动应该只展现壹般的错误音讯。
  • 设想工作逻辑攻击。例如,攻击者能够跳过多步骤的预约流程来预定产品而无需输入信用卡音信呢?
  • 对思疑的位移记录日志。

  RESTful安全必要专注的地点:

  • 注脚数据的JSON和XML格式。
  • HTTP动词应该被限定在同意的措施中。例如,GET请求无法去除1个实体。GET用来读取实体而DELETE用来删除实体。
  • 留意race
    conditions(竞争规则——由于七个也许多少个进度竞争使用无法被同时做客的财富,使得那些经过有非常大可能率因为时间上助长的次第原由此产出难题)。

  API网关可用于监视、限制和决定对API的访问。以下内容可由网关或RESTful服务完成。

  • 蹲点API的采用状态,并打听怎么活动是平常的,哪些是非正常的。
  • 限制API的运用,使恶意用户不能够停掉1个API服务(DOS攻击),并且有工夫阻止恶意的IP地址。
  • 将API密钥存款和储蓄在加密的平安密钥库中。

 

缓存和可伸缩性

  通过在系统层级化解通过远程调用来博取请求的多寡,缓存进步了系统的可增添性。服务通过在响应中安装headers来狠抓缓存的工夫。遗憾的是,HTTP
1.0中与缓存相关的headers与HTTP
1.壹不一,由此服务器要同时补助二种版本。下表给出了GET请求要援救缓存所必须的最少headers集合,并付诸了方便的描述。

HTTP Header

描述

示例

Date

一呼百应重回的日期和时间(EscortFC11二三格式)。

Date: Sun, 06 Nov 1994 08:49:37 GMT

Cache-Control

响应可被缓存的最大秒数(最大age值)。假使响应不扶助缓存,值为no-cache。

Cache-Control: 360

Cache-Control: no-cache

Expires

借使给出了最大age值,该时间戳(BMWX三FC112三格式)表示的是响应过期的年月,也正是Date(例如当今天子)加上最大age值。即使响应不帮助缓存,该headers不存在。

Expires: Sun, 06 Nov 1994 08:49:37 GMT

Pragma

当Cache-Control为no-cache时,该header的值也被设置为no-cahche。不然,不设有。

Pragma: no-cache

Last-Modified

财富本人最后被修改的年月戳(智跑FC112叁格式)。

Last-Modified: Sun, 06 Nov1994 08:49:37 GMT

  为了简化,那里举一个响应中的headers集合的例子。那是一个简易的对财富拓展GET请求的响应,缓存时间长度为一天(二四钟头):

  Cache-Control: 86400
  Date: Wed, 29 Feb 2012 23:01:10 GMT
  Last-Modified: Mon, 28 Feb 2011 13:10:14 GMT
  Expires: Thu, 01 Mar 2012 23:01:10 GMT

  下边是2个看似的例子,不过缓存被统统禁止使用:

  Cache-Control: no-cache
  Pragma: no-cache

缓存和可伸缩性

  通过在系统层级解决通过中距离调用来获得请求的数目,缓存升高了系统的可扩张性。服务通过在响应中装置headers来加强缓存的工夫。遗憾的是,HTTP
壹.0中与缓存相关的headers与HTTP
一.一见仁见智,由此服务器要同时帮忙两种版本。下表给出了GET请求要帮忙缓存所必须的最少headers集合,并提交了方便的叙说。

HTTP Header

描述

示例

Date

一呼百应重回的日子和时间(智跑FC11二叁格式)。

Date: Sun, 06 Nov 1994 08:49:37 GMT

Cache-Control

响应可被缓存的最大秒数(最大age值)。如若响应不援救缓存,值为no-cache。

Cache-Control: 360

Cache-Control: no-cache

Expires

假定给出了最大age值,该时间戳(奥迪Q5FC1123格式)表示的是响应过期的时刻,也便是Date(例如当前些天子)加上最大age值。假如响应不支持缓存,该headers不设有。

Expires: Sun, 06 Nov 1994 08:49:37 GMT

Pragma

当Cache-Control为no-cache时,该header的值也被设置为no-cahche。不然,不设有。

Pragma: no-cache

Last-Modified

能源自个儿最后被修改的时刻戳(中华VFC11二3格式)。

Last-Modified: Sun, 06 Nov1994 08:49:37 GMT

  为了简化,那里举2个响应中的headers集合的事例。那是贰个简易的对能源开始展览GET请求的响应,缓存时间长度为壹天(二四时辰):

  Cache-Control: 86400
  Date: Wed, 29 Feb 2012 23:01:10 GMT
  Last-Modified: Mon, 28 Feb 2011 13:10:14 GMT
  Expires: Thu, 01 Mar 2012 23:01:10 GMT

  下边是二个接近的例子,可是缓存被全然禁止使用:

  Cache-Control: no-cache
  Pragma: no-cache

ETag Header

  ETag
header对于注脚缓存数据的新旧程度很有用,同时也助长条件的读取和翻新操作(分别为GET和PUT)。它的值是叁个任意字符串,用来表示回到数据的本子。可是,对于重返数据的不及格式,它也足以不一样——JSON格式响应的ETag与同1财富XML格式响应的ETag会差异。ETag
header的值可以录像带有格式的底层域对象的哈希表(例如Java中的Obeject.hashcode())同样简单。指出为各种GET(读)操作重临三个ETag
header。别的,确认保证用双引号包蕴ETag的值,例如:

  ETag: “686897696a7c876b7e”

 

ETag Header

  ETag
header对于评释缓存数据的新旧程度很有用,同时也有助于条件的读取和革新操作(分别为GET和PUT)。它的值是多个任意字符串,用来表示回到数据的版本。可是,对于重回数据的不等格式,它也足以差异——JSON格式响应的ETag与同等资源XML格式响应的ETag会分歧。ETag
header的值能够录像带有格式的底层域对象的哈希表(例如Java中的Obeject.hashcode())同样轻松。建议为各类GET(读)操作再次来到三个ETag
header。其它,确定保障用双引号包罗ETag的值,例如:

  ETag: “686897696a7c876b7e”

 

HTTP状态码(前10)

  以下是由RESTful服务或API重临的最常用的HTTP状态码,以及部分有关它们广泛用法的简练表达。其余HTTP状态码不太常常利用,它们照旧更奇特,要么越来越尖端。大繁多劳动套件只补助那几个常用的状态码,甚至只扶助在那之中的一局地,并且它们都能符合规律干活。

  200 (OK) —— 平常的中标景色。表示成功的最广泛代码。

  201 (CREATED) ——(通过POST或PUT)创设成功。通过安装Location
header来含有二个对准最新成立的财富的链接。

  204 (NO CONTENT)
—— 封装过的响应未有行使,或body中并未有别的内容时(如DELETE),使用该意况。

  304 (NOT MODIFIED)
—— 用于有标准的GET调用的响应,以减弱带宽的施用。
假若应用该情况,那么必须为GET调用设置Date、Content-Location和ETag
headers。不含有响应体。

  400 (BAD REQUEST)
—— 用于实行请求时或许滋生无效状态的相似错误代码。如域名无效错误、数据丢失等。

  401 (UNAUTHORIZED)
—— 用于贫乏认证token或申明token无效的错误代码。

  403 (FORBIDDEN)
—— 未授权的用户推行操作,未有权力访问财富,恐怕是因为某个原因财富不可用(如时限等),使用该错误码。

  404 (NOT FOUND)
—— 无论能源存不设有,无论是还是不是有40一、40三的限制,当呼吁的财富找不到时,出于安全因素思索,服务器都足以动用该错误码来掩盖。

  409 (CONFLICT)
—— 每当实践请求恐怕会挑起能源争辨时行使。例如,存在重新的实业,当不协理级联删除时去除根对象。

  500 (INTERNAL SERVER ERROR)
—— 当服务器抛出至极时,捕捉到的形似错误。

 

HTTP状态码(前10)

  以下是由RESTful服务或API再次来到的最常用的HTTP状态码,以及一些有关它们广泛用法的简要表明。别的HTTP状态码不太平常应用,它们依旧更卓越,要么更加高档。大大多服务套件只扶助那些常用的状态码,甚至只协助当中的一部分,并且它们都能健康办事。

  200 (OK) —— 常常的打响景观。表示成功的最普及代码。

  201 (CREATED) ——(通过POST或PUT)创形成功。通过安装Location
header来含有二个针对性最新创立的资源的链接。

  204 (NO CONTENT)
—— 封装过的响应未有运用,或body中未有其余内容时(如DELETE),使用这场馆。

  304 (NOT MODIFIED)
—— 用于有规范的GET调用的响应,以调整和减弱带宽的选用。
固然选拔这场地,那么必须为GET调用设置Date、Content-Location和ETag
headers。不带有响应体。

  400 (BAD REQUEST)
—— 用于试行请求时只怕引起无效状态的一般错误代码。如域名无效错误、数据丢失等。

  401 (UNAUTHORIZED)
—— 用于缺乏认证token或表明token无效的错误代码。

  403 (FORBIDDEN)
—— 未授权的用户实施操作,未有权力访问能源,大概是因为有些原因能源不可用(如时限等),使用该错误码。

  404 (NOT FOUND)
—— 无论能源存不存在,无论是不是有401、40三的范围,当呼吁的财富找不到时,出于安全因素思量,服务器都足以动用该错误码来掩盖。

  409 (CONFLICT)
—— 每当试行请求或者会唤起财富争执时利用。例如,存在双重的实业,当不匡助级联删除时去除根对象。

  500 (INTERNAL SERVER ERROR)
—— 当服务器抛出至极时,捕捉到的形似错误。

 

叠加能源

叠加能源

书籍

  REST API Design Rulebook,Mark Masse, 2011, O’Reilly Media, Inc.

  RESTful Web Services, Leonard Richardson and Sam Ruby, 2008,
O’Reilly Media, Inc.

*  RESTful Web Services Cookbook, Subbu Allamaraju, 2010, O’Reilly
Media, Inc.*

  REST in Practice: Hypermedia and Systems Architecture, Jim Webber,
et al., 2010, O’Reilly Media, Inc.

  APIs: A Strategy Guide, Daniel Jacobson; Greg Brail; Dan Woods,
2011, O’Reilly Media, Inc.

书籍

  REST API Design Rulebook,Mark Masse, 2011, O’Reilly Media, Inc.

  RESTful Web Services, Leonard Richardson and Sam Ruby, 2008,
O’Reilly Media, Inc.

*  RESTful Web Services Cookbook, Subbu Allamaraju, 2010, O’Reilly
Media, Inc.*

  REST in Practice: Hypermedia and Systems Architecture, Jim Webber,
et al., 2010, O’Reilly Media, Inc.

  APIs: A Strategy Guide, Daniel Jacobson; Greg Brail; Dan Woods,
2011, O’Reilly Media, Inc.

网站

  http://www.restapitutorial.com
http://www.toddfredrich.com

  http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
  http://www.json.org/
https://github.com/tfredrich/DateAdapterJ

  http://openid.net/developers/specs/
  http://oauth.net/documentation/spec/
  http://www.json.org/JSONRequest.html
http://labs.omniti.com/labs/jsend

  http://enable-cors.org/
  http://www.odata.org/documentation/uri-conventions#FilterSystemQueryOption
  http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
  https://developer.linkedin.com/apis
  http://developers.facebook.com/docs/reference/api/
  https://dev.twitter.com/docs/api
http://momentjs.com/

  http://www.datejs.com/

 

在原翻译的根底上经过改变:http://blog.csdn.net/huayuqa/article/details/62237010

英文原来的书文下载:RESTful Best Practices-v1
2.pdf

网站

  http://www.restapitutorial.com
http://www.toddfredrich.com

  http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
  http://www.json.org/
https://github.com/tfredrich/DateAdapterJ

  http://openid.net/developers/specs/
  http://oauth.net/documentation/spec/
  http://www.json.org/JSONRequest.html
http://labs.omniti.com/labs/jsend

  http://enable-cors.org/
  http://www.odata.org/documentation/uri-conventions#FilterSystemQueryOption
  http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
  https://developer.linkedin.com/apis
  http://developers.facebook.com/docs/reference/api/
  https://dev.twitter.com/docs/api
http://momentjs.com/

  http://www.datejs.com/

 

在原翻译的底蕴上经过修改:http://blog.csdn.net/huayuqa/article/details/62237010

英文原作下载:RESTful Best Practices-v1
2.pdf

相关文章