据书上说资源,基于能源

正文首要读者

本文主要读者

引言

引言

REST是什么

REST是什么

  集合接口

  联合接口

    根据财富

    基于财富

    因而特色来操作财富

    经过特色来操作能源

    自描述的新闻

    自描述的音讯

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

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

  无状态

  无状态

  可缓存

  可缓存

  C-S架构

  C-S架构

  分段系统

  支行系统

  按需编码(可选)

  按需编码(可选)

REST神速提示

REST快捷提示

  使用HTTP动词表示一些含义

  利用HTTP动词表示一些意思

  合理的财富名

  客观的能源名

  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服务感兴趣的开发职员,该服务为跨多少个劳务的零件提供了较高的可信性和一致性。依照本文的指点,可高效、广泛、公开地为内外部客户接纳。

  本文中的带领规范一致适用于工程师们,他们愿意采纳这一个遵照最棒实践标准开发的劳动。就算她们越发关切缓存、代理规则、监听及康宁等相关方面,可是该文书档案能作为一份包蕴全部项目服务的总指南。

  其它,通过从那么些辅导原则,管理人士领悟到创制公共的、提供高稳定性的劳动所需费用的鼎力,他们也可从中收益。

 

本文首要读者

  该最好实践文档适用于对RESTful
Web服务感兴趣的开发人士,该服务为跨八个服务的零件提供了较高的可信赖性和一致性。依照本文的点拨,可高效、广泛、公开地为内外部客户使用。

  本文中的辅导规范一致适用于工程师们,他们盼望利用这一个依据最好实践标准开发的劳动。即便他们愈发关切缓存、代理规则、监听及康宁等休戚相关方面,但是该文书档案能作为一份包蕴全体品类服务的总指南。

  别的,通过从那些指点标准,管理职员驾驭到开创公共的、提供高稳定性的服务所需开销的卖力,他们也可从中收益。

 

引言

  于今已有恢宏有关RESTful
Web服务至上实践的相干资料(详见本文最终的有关文献部分)。由于撰文的年月分裂,许多材料中的内容是冲突的。此外,想要通过翻看文献来打听那种劳动的提升是不太可取的。为了驾驭RESTful这一概念,至少需求查阅三到五本有关文献,而本文将能够帮您加快这一进度——抛弃多余的议论,最大化地提炼出REST的特等实践和规范。

  与其说REST是一套标准,REST更像是一种标准的聚合。除了两个重点的基准外就从未有过任何的正经了。实际上,即使有所谓的“最好实践”和正规,但这一个事物都和宗教斗争一样,在不停地演化。

  本文围绕REST的大面积难点提议了看法和仿食谱式的研讨,并因而介绍部分简便的背景知识对创造真实情形下的预生产条件中一律的REST服务提供文化。本文收集了来自其它渠道的消息,经历过二遍次的破产后不断革新。

  但对于REST格局是或不是必然比SOAP好用仍有较大争议(反之亦然),或许在少数景况下仍急需创建SOAP服务。本文在提及SOAP时并未花较大篇幅来谈谈它的相对优点。相反由于技术和行业在不断进步,我们将持续持之以恒咱们的假如–REST是随即安排web服务的超级办法。

  第2有些概述REST的意思、设计准则和它的不一致通常之处。第1局地点数了一部分小贴士来回忆REST的劳动理念。之后的一部分则会更深远地为web服务创建人员提供部分细节的支撑和座谈,来兑现二个能够公开始展览示在生育环境中的高质量REST服务。

 

引言

  于今已有大气有关RESTful
Web服务至上实践的相干材质(详见本文最终的有关文献部分)。由于撰文的大运各异,许多素材中的内容是争辨的。此外,想要通过查阅文献来打探那种服务的提高是不太可取的。为了打探RESTful这一定义,至少需求查阅三到五本有关文献,而本文将能够帮你加速这一进程——扬弃多余的座谈,最大化地提炼出REST的一级实践和正规。

  与其说REST是一套标准,REST更像是一种规格的集纳。除了多少个十分重要的标准外就从不别的的正规了。实际上,固然有所谓的“最好实践”和标准,但这几个事物都和宗教斗争一样,在相连地演化。

  本文围绕REST的大规模难题提议了意见和仿食谱式的议论,并通过介绍部分简练的背景知识对创造真实境况下的预生产环境中平等的REST服务提供文化。本文收集了来自其它渠道的新闻,经历过1次次的破产后不断立异。

  但对于REST格局是不是必然比SOAP好用仍有较大争议(反之亦然),可能在有些意况下仍供给创造SOAP服务。本文在提及SOAP时并未花较大篇幅来谈谈它的周旋优点。相反由于技术和行业在不断进步,大家将继承坚忍不拔大家的只要–REST是随即陈设web服务的最好方法。

  第①部分概述REST的意思、设计准则和它的特殊之处。第①某个列举了有的小贴士来回忆REST的劳动意见。之后的一部分则会更尖锐地为web服务创造职员提供部分细节的帮忙和座谈,来完成3个能够驾驭映今后生产环境中的高品质REST服务。

 

REST是什么?

  REST架构方式讲述了多种设计准则。这几个用于架构的筹划准则,最早是由RoyFielding在她的学士杂文中提议并定义了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架构
  • 分层系统
  • 按需编码

  以下是这几个规划准则的事无巨细谈论:

统一接口

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

统一接口

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

  基于能源

  分歧财富供给用U汉兰达I来唯一标识。重返给客户端的特性和财富本人在概念上有所差异,例如服务端不会直接传送3个数据库财富,可是,一些HTML、XML或JSON数据可见显得部分数据库记录,如用斯洛伐克语来表述照旧用UTF-8编码则要依照请求和服务器达成的底细来决定。

  基于能源

  分歧财富要求用U帕杰罗I来唯一标识。重回给客户端的特点和能源本身在概念上有所不一致,例如服务端不会平素传送叁个数据库财富,可是,一些HTML、XML或JSON数据可知彰显部分数据库记录,如用瑞典语来发布依旧用UTF-8编码则要依据请求和服务器达成的细节来决定。

  通过特征来操作能源

  当客户端收到包罗元数据的财富的性状时,在有权力的状态下,客户端已领会的十足的音信,能够对服务端的财富拓展删改。

  通过特征来操作财富

  当客户端收到包罗元数据的财富的特征时,在有权力的情状下,客户端已理解的十足的新闻,能够对服务端的能源开始展览删改。

  自描述的音讯

  每条音讯都带有充足的数目用于确认新闻该怎么处理。例如要由网络媒体类型(已知的如MIME类型)来确认需调用哪个解析器。响应同样也表明了它们的缓存能力。

  自描述的新闻

  每条音讯都包含丰裕的数额用于确认消息该怎么处理。例如要由互连网媒体类型(已知的如MIME类型)来认同需调用哪个解析器。响应同样也标志了它们的缓存能力。

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

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

  除了上述内容外,HATEOS也代表,须要的时候链接也可被含有在回到的body(或尾部)中,以提供UGL450I来寻找对象自作者或关系对象。下文将对此进行更详尽的阐释。

  统一接口是各样REST服务规划时的必需准则。

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

  客户端通过body内容、查询串参数、请求头和U汉兰达I(资源名称)来传送状态。服务端通过body内容,响应码和响应头传送状态给客户端。那项技能被号称超媒体(或超文本链接)。

  除了上述剧情外,HATEOS也意味,供给的时候链接也可被含有在回来的body(或头部)中,以提供UOdysseyI来搜寻对象自小编或涉嫌对象。下文将对此开展更详尽的阐发。

  统一接口是各样REST服务规划时的画龙点睛准则。

无状态

  正如REST是REpresentational State
Transfer的缩写,无状态很重点。本质上,那申明了拍卖请求所需的景况已经包涵在呼吁我里,也有或然是U兰德奥德赛I的一有个别、查询串参数、body或底部。USportageI能够唯一标识每一个资源,body中也包涵了财富的转态(或转态变更情状)。之后,服务器将拓展处理,将有关的景况或财富通过尾部、状态和响应body传递给客户端。

  从事大家这一行业的绝超过四分之1人都习惯使用容器来编制程序,容器中有2个“会话”的定义,用于在多少个HTTP请求下维持状态。在REST中,假若要在八个请求下保持用户景况,客户端必须回顾客户端的保有新闻来成功请求,须求时再也发送请求。自从服务端不必要有限支撑、更新或传递会话状态后,无状态性获得了更大的延展。别的,负载均衡器无需担心和无状态系统里面的对话。

  所以状态和能源间有怎么样差距?服务器对于状态,恐怕说是应用状态,所关心的点是在现阶段对话或请求中要到位请求所需的数据。而能源,恐怕说是财富气象,则是概念了财富特色的数量,例如存款和储蓄在数据库中的数据。不问可见,应用状态是是随着客户端和伸手的改动而更改的数额。相反,能源景况对于发出请求的客户端的话是不变的。

  在互连网利用的某一特定岗位上摆放2个回来按钮,是因为它愿意你能按自然的各种来操作吗?其实是因为它违反了无状态的口径。有为数不少不屈从无状态原则的案例,例如3-Legged
OAuth,API调用速度限制等。但要么要尽大概保障服务器中不须要在多少个请求下维持利用状态。

无状态

  正如REST是REpresentational State
Transfer的缩写,无状态很关键。本质上,那注解了处理请求所需的状态已经包括在伸手作者里,也有恐怕是ULacrosseI的一有的、查询串参数、body或底部。UEscortI能够唯一标识每一个财富,body中也暗含了能源的转态(或转态变更情形)。之后,服务器将进行拍卖,将有关的气象或财富通过底部、状态和响应body传递给客户端。

  从事大家这一行业的多数人都习惯使用容器来编制程序,容器中有一个“会话”的定义,用于在三个HTTP请求下保持状态。在REST中,倘若要在七个请求下保持用户意况,客户端必须回顾客户端的具有音信来完结请求,供给时再度发送请求。自从服务端不须求保持、更新或传递会话状态后,无状态性获得了更大的延展。别的,负载均衡器无需担心和无状态系统里头的对话。

  所以状态和财富间有何异样?服务器对于状态,可能说是应用状态,所关心的点是在时下对话或请求中要做到请求所需的多寡。而能源,可能说是财富景况,则是概念了能源特色的数据,例如存款和储蓄在数据库中的数据。同理可得,应用状态是是随着客户端和哀告的变更而变更的数码。相反,财富情况对于发出请求的客户端的话是不变的。

  在网络使用的某一特定岗位上摆放一个赶回按钮,是因为它仰望你能按自然的逐一来操作吗?其实是因为它违反了无状态的尺码。有过多不信守无状态原则的案例,例如3-Legged
OAuth,API调用速度限制等。但要么要硬着头皮保险服务器中不必要在七个请求下维持利用状态。

可缓存

  在万维网上,客户端能够缓存页面包车型客车响应内容。因而响应都应隐式或显式的定义为可缓存的,若不足缓存则要防止客户端在反复呼吁后用旧数据或脏数据来响应。管理稳当的缓存会部分地或完全地除了客户端和服务端之间的互相,进一步创新品质和延展性。

可缓存

  在万维网上,客户端能够缓存页面包车型客车响应内容。由此响应都应隐式或显式的定义为可缓存的,若不足缓存则要制止客户端在延续请求后用旧数据或脏数据来响应。管理妥当的缓存会部分地或完全地除了客户端和服务端之间的竞相,进一步创新质量和延展性。

C-S架构

  统一接口使得客户端和服务端相互分开。关心分离意味什么?打个即便,客户端不须要仓库储存数据,数据都留在服务端内部,那样使得客户端代码的可移植性获得了升级;而服务端不供给考虑用户接口和用户情形,那样一来服务端将尤其简约易拓展。只要接口不改变,服务端和客户端能够单独地开展研究开发和替换。

C-S架构

  统一接口使得客户端和服务端互相分开。关心分离意味什么?打个若是,客户端不需求仓库储存数据,数据都留在服务端内部,那样使得客户端代码的可移植性拿到了提拔;而服务端不必要考虑用户接口和用户景况,那样一来服务端将尤为简明易拓展。只要接口不转移,服务端和客户端能够独自地拓展研究开发和替换。

支行系统

  客户端平日不能够表明本身是直接或许直接与端服务器实行连接。中介服务器能够由此启用负载均衡或提供共享缓存来提高系统的延展性。分层时一样要考虑安全策略。

支行系统

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

按需编码(可选)

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

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

  提示:REST架构中的安排准则中,唯有按需编码为可选项。假诺某些服务违反了别的随意一项准则,严刻意思上无法称之为RESTful风格。

 

按需编码(可选)

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

  遵守上述标准,与REST架构风格保持一致,能让各样分布式超媒连串统有着梦想的自然属性,比如高质量,延展性,简洁,可变性,可视化,可移植性和可信赖性。

  提示:REST架构中的安排性准则中,只有按需编码为可选项。要是有个别服务违反了其他随意一项准则,严刻意思上不可能称之为RESTful风格。

 

REST火速提示

  (依照地方提到的两个标准)不管在技术上是还是不是RESTful的,那里有局地近乎REST概念的建议。遵循它们,能够兑现更好、更实惠的劳动:

REST赶快提示

  (依据上面提到的八个条件)不管在技术上是还是不是RESTful的,那里有部分类似REST概念的提出。遵守它们,能够达成更好、更实用的劳动:

接纳HTTP动词表示一些含义

  任何API的使用者可以发送GET、POST、PUT和DELETE请求,它们不小程度鲜明了所给请求的目的。同时,GET请求不能改变任何秘密的能源数量。度量和跟踪仍恐怕产生,但只会更新数据而不会更新由U逍客I标识的财富数量。

使用HTTP动词表示一些意义

  任何API的使用者能够发送GET、POST、PUT和DELETE请求,它们不小程度明显了所给请求的目标。同时,GET请求不可能改变任何秘密的能源数量。度量和跟踪仍恐怕发生,但只会更新数据而不会更新由U揽胜极光I标识的财富数量。

客观的能源名

  合理的能源名称也许路径(如/posts/23而不是/api?type=posts&id=23)能够更引人侧目二个呼吁的指标。使用UCR-VL查询串来过滤数据是很好的法子,但不应有用于固定能源名称。

  适当的财富名称为服务端请求提供上下文,增添服务端API的可通晓性。通过U翼虎I名称分层地查看能源,能够给使用者提供一个要好的、简单掌握的资源层次,以在他们的应用程序上应用。财富名称应当是名词,制止为动词。使用HTTP方法来内定请求的动作部分,能让工作更是的清晰。

理所当然的财富名

  合理的财富名称只怕路径(如/posts/23而不是/api?type=posts&id=23)能够更显著二个伸手的指标。使用U昂CoraL查询串来过滤数据是很好的法子,但不该用于固定财富名称。

  适当的财富名称为服务端请求提供上下文,扩大服务端API的可精通性。通过U瑞鹰I名称分层地翻看财富,能够给使用者提供一个投机的、简单精通的能源层次,以在她们的应用程序上选取。财富名称应当是名词,幸免为动词。使用HTTP方法来钦点请求的动作部分,能让工作越来越的明掌握白。

XML和JSON

  建议默许扶助json,并且,除非费用很惊人,不然就同时辅助json和xml。在赏心悦目图景下,让使用者仅透过变更扩张名.xml和.json来切换类型。其余,对于支撑ajax风格的用户界面,三个被包裹的响应是卓殊有帮扶的。提供二个被打包的响应,在暗许的依然有单独扩充名的状态下,例如:.wjson和.wxml,申明客户端请求3个被包裹的json或xml响应(请参见上面包车型客车包装响应)。

  “标准”中对json的渴求很少。并且那一个须要只是语法性质的,毫不相关内容格式和布局。换句话说,REST服务端调用的json响应是协商的一片段——在专业中尚无相关描述。越来越多关于json数据格式能够在http://www.json.org/上找到。

  关于REST服务中xml的选择,xml的科班和平条约定除了选拔语法正确的标签和文本外没有其余的效用。更加地,命名空间不是也不应该是被接纳在REST服务端的左右文中。xml的回到更近乎于json——简单、不难阅读,没有格局和命名空间的底细呈现——仅仅是数据和链接。要是它比那更复杂的话,参看本节的首先段——使用xml的本金是耸人据说的。鉴于大家的经验,很少有人利用xml作为响应。在它被统统淘汰此前,那是最终1个可被肯定的地方。

XML和JSON

  提出暗中认可支持json,并且,除非花费很震惊,不然就同时匡助json和xml。在精粹状态下,让使用者仅透过变更扩张名.xml和.json来切换类型。其余,对于帮助ajax风格的用户界面,二个棉被服装进的响应是那八个有援助的。提供一个被包裹的响应,在暗中认可的要么有独立扩充名的气象下,例如:.wjson和.wxml,申明客户端请求二个被卷入的json或xml响应(请参见下边的卷入响应)。

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

  关于REST服务中xml的利用,xml的行业内部和预约除了利用语法正确的竹签和文本外没有其他的职能。特别地,命名空间不是也不该是被运用在REST服务端的前后文中。xml的回到更类似于json——简单、简单阅读,没有方式和命名空间的细节表现——仅仅是数额和链接。假若它比那更复杂的话,参看本节的第1段——使用xml的血本是惊心动魄的。鉴于我们的经验,很少有人使用xml作为响应。在它被统统淘汰之前,那是终极3个可被肯定的地方。

始建适当粒度的能源

  一发轫,系统中模拟底层应用程序域或数据库架构的API更易于被创设。最后,你会期待将这么些服务都构成到二只——利用多项底层财富减弱通讯量。在创建独立的能源之后再成立更大粒度的财富,比从更大的合集中创造较大粒度的财富越是不难一些。从部分小的不难定义的能源开端,创造CRUD(增加和删除查改)作用,能够使财富的创始变得更易于。随后,你可以创设这个依据用例和压缩通讯量的能源。

始建适当粒度的能源

  一初始,系统中模拟底层应用程序域或数据库架构的API更便于被成立。最后,你会期待将这个服务都构成到手拉手——利用多项底层能源减弱通讯量。在创建独立的能源之后再成立更大粒度的能源,比从更大的合集中创制较大粒度的财富尤其简单一些。从部分小的不难定义的财富早先,创立CRUD(增加和删除查改)作用,能够使能源的创办变得更便于。随后,你能够创立那些依据用例和收缩通讯量的财富。

设想连通性

  REST的规律之一正是连通性——通过超媒体链接完成。当在响应中回到链接时,api变的更兼具自描述性,而在未曾它们时服务端还是可用。至少,接口自己可以为客户端提供什么寻找数据的参考。其余,在通过POST方法创制财富时,还足以选拔头地方包罗贰个链接。对于响应中扶助分页的集聚,”first”、
“last”、”next”、和”prev”链接至少是特别实惠的。

 

考虑连通性

  REST的规律之一正是连通性——通过超媒体链接实现。当在响应中回到链接时,api变的更富有自描述性,而在并未它们时服务端如故可用。至少,接口本身能够为客户端提供什么样寻找数据的参照。别的,在通过POST方法成立财富时,还足以应用头地点包蕴1个链接。对于响应中帮助分页的成团,”first”、
“last”、”next”、和”prev”链接至少是可怜管用的。

 

定义

定义

幂等性

  不要从字面意思来通晓什么是幂等性,恰恰相反,那与有些意义紊乱的领域非亲非故。上面是来源于维基百科的解说:

在处理器科学中,术语幂等用于更周到地叙述1个操作,三遍或频仍推行该操作发生的结果是同一的。依照使用的上下文,那可能有差异的意义。例如,在章程大概子例程调用拥有副功效的图景下,意味着在第叁调用之后被修改的情况也保持不变。

  从REST服务端的角度来看,由于操作(或服务端调用)是幂等的,客户端能够用重新的调用而爆发同样的结果——在编制程序语言中操作像是三个”setter”(设置)方法。换句话说,正是运用八个相同的请求与使用单个请求效果一样。注意,当幂等操作在服务器上发生相同的结果(副成效),响应本人恐怕是差异的(例如在多个请求之间,能源的情形大概会变动)。

  PUT和DELETE方法被定义为是幂等的。查看http请求中delete动词的警告音信,能够参考下文的DELETE部分。GET、HEAD、OPTIO和TRACE方法自从被定义为安全的格局后,也被定义为幂等的。参照上面关于安全的段落。

幂等性

  不要从字面意思来领会什么是幂等性,恰恰相反,那与某个职能紊乱的天地无关。下边是缘于维基百科的解释:

在处理器科学中,术语幂等用于更健全地描述3个操作,二遍或频仍执行该操作爆发的结果是如出一辙的。依据使用的上下文,那大概有例外的含义。例如,在格局或者子例程调用拥有副功能的境况下,意味着在率先调用之后被改动的情状也维持不变。

  从REST服务端的角度来看,由于操作(或服务端调用)是幂等的,客户端能够用重新的调用而发出同样的结果——在编制程序语言中操作像是1个”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)操作。也有许多其余的动词,不过选用功能比较低。在那几个应用较少的办法中,OPTIONS和HEAD往往选用得更加多。

HTTP动词

  Http动词首要听从“统一接口”规则,并提须要大家相应的依照名词的财富的动作。最重要依然最常用的http动词(或者叫做方法,那样称呼或许更得当些)有POST、GET、PUT和DELETE。这个分别对应于创设、读取、更新和删除(CRUD)操作。也有无数别的的动词,不过利用成效相比低。在那么些应用较少的措施中,OPTIONS和HEAD往往选拔得越来越多。

GET

  HTTP的GET方法用于检索(或读取)财富的数目。在正确的伏乞路径下,GET方法会重临二个xml大概json格式的数码,以及3个200的HTTP响应代码(表示正确重返结果)。在错误景况下,它一般重临404(不设有)或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回和调用11次依然没有被调用的效用一样。其它,GET(以及HEAD)是幂等的,那代表使用八个一律的呼吁与行使单个的伸手最后都兼备同等的结果。

  不要通过GET暴光不安全的操作——它应有永远都没办法改改服务器上的别样财富。

GET

  HTTP的GET方法用于检索(或读取)财富的数额。在正确的乞请路径下,GET方法会重返二个xml恐怕json格式的多少,以及2个200的HTTP响应代码(表示正确再次回到结果)。在错误意况下,它一般重临404(不设有)或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)请求仅用于读取数据而不更改多少。由此,那种使用办法被认为是平安的。也便是说,它们的调用没有数据修改或污染的高危害——调用2次和调用11次如故没有被调用的功用一样。别的,GET(以及HEAD)是幂等的,那代表使用两个一律的呼吁与行使单个的伸手最后都兼备同样的结果。

  不要通过GET揭示不安全的操作——它应该永远都不可能修改服务器上的此外国资本源。

PUT

  PUT日常被用于更新财富。通过PUT请求3个已知的财富U途乐I时,需求在哀告的body中含有对原本能源的立异数据。

  但是,在财富ID是由客服端而非服务端提供的图景下,PUT同样能够被用来创制能源。换句话说,如若PUT请求的UENVISIONI中含有的能源ID值在服务器上不设有,则用来创制能源。同时伸手的body中必须含有要创设的财富的数额。有人认为那会生出歧义,所以唯有真的须要,使用那种方式来创建财富应该被慎用。

  大概大家也得以在body中提供由客户端定义的能源ID然后使用POST来创制新的财富——假如请求的U景逸SUVI中不含有要开创的财富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(大概重临204,表示回去的body中不分包别的内容)。若是接纳PUT请求创立能源,成功再次来到的HTTP状态码是201。响应的body是可选的——假设提供的话将会开销更多的带宽。在开立财富时未尝须求通过尾部的职务重返链接,因为客户端已经安装了能源ID。请参见上面包车型大巴重返值部分。

  PUT不是三个张家界的操作,因为它会修改(或创设)服务器上的状态,但它是幂等的。换句话说,要是你选择PUT创设恐怕更新能源,然后重新调用,能源还是存在并且状态不会发生变化。

  例如,尽管在能源增量计数器中调用PUT,那么这么些调用方法就不再是幂等的。这种气象有时候会时有发生,且只怕能够注脚它是非幂等性的。然则,建议维持PUT请求的幂等性。并强烈提议非幂等性的央求使用POST。

PUT

  PUT平常被用来革新财富。通过PUT请求3个已知的财富UCRUISERI时,须要在呼吁的body中富含对原有财富的换代数据。

  不过,在能源ID是由客服端而非服务端提供的情事下,PUT同样能够被用来创制能源。换句话说,如若PUT请求的U揽胜I中涵盖的能源ID值在服务器上不存在,则用于创制能源。同时请求的body中务必包罗要开创的资源的数目。有人以为那会时有产生歧义,所以唯有真的必要,使用那种方法来创立财富应该被慎用。

  或然我们也足以在body中提供由客户端定义的财富ID然后使用POST来创制新的能源——即便请求的UEscortI中不分包要创造的能源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(恐怕再次来到204,表示回去的body中不包涵其余内容)。要是运用PUT请求创造能源,成功再次来到的HTTP状态码是201。响应的body是可选的——若是提供的话将会开支越来越多的带宽。在创制财富时未尝要求通过尾部的职位重临链接,因为客户端已经安装了财富ID。请参见上面包车型大巴再次回到值部分。

  PUT不是3个康宁的操作,因为它会修改(或创建)服务器上的动静,但它是幂等的。换句话说,借使您选用PUT成立大概更新财富,然后再次调用,财富还是存在并且状态不会爆发变化。

  例如,假若在资源增量计数器中调用PUT,那么这几个调用方法就不再是幂等的。那种意况有时候会生出,且大概能够表明它是非幂等性的。但是,提出维持PUT请求的幂等性。并强烈提出非幂等性的乞请使用POST。

POST

  POST请求平时被用来创制新的能源,特别是被用来创制从属财富。从属财富即归属于其余能源(如父能源)的财富。换句话说,当创设二个新能源时,POST请求发送给父能源,服务端负责将新能源与父财富拓展关联,并分配七个ID(新财富的U福特ExplorerI),等等。

  例如:

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

  当创立成功时,重临HTTP状态码201,并顺便一个职位头消息,在那之中含有指向先河创造的能源的链接。

  POST请求既不是平安的又不是幂等的,由此它被定义为非幂等性财富请求。使用多个一律的POST请求很也许会造成成立七个包括相同音信的财富。

POST

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

  例如:

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

  当创设成功时,重返HTTP状态码201,并顺便2个职位头音讯,在这之中包罗指向初叶创制的财富的链接。

  POST请求既不是平安的又不是幂等的,由此它被定义为非幂等性财富请求。使用七个相同的POST请求很也许会导致创制多个带有相同信息的能源。

PUT和POST的开创相比较

  显而易见,大家提议利用POST来创制财富。当由客户端来控制新能源具有哪些U奥迪Q5I(通过能源名称或ID)时,使用PUT:即假若客户端知道U奥迪Q5I(或能源ID)是怎样,则对该UCRUISERI使用PUT请求。不然,当由服务器或服务端来支配创办的财富的U兰德福睿斯I时则应用POST请求。换句话说,当客户端在开立以前不晓得(或不能知道)结果的UPAJEROI时,使用POST请求来创建新的财富。

PUT和POST的开创比较

  由此可见,我们建议采纳POST来创造能源。当由客户端来控制新资源有着何等URubiconI(通过财富名称或ID)时,使用PUT:即假如客户端知道U汉兰达I(或财富ID)是怎么着,则对该UEnclaveI使用PUT请求。不然,当由服务器或服务端来决定成立的财富的U奔驰G级I时则选拔POST请求。换句话说,当客户端在开立在此以前不亮堂(或一点都不大概清楚)结果的U本田UR-VI时,使用POST请求来成立新的能源。

DELETE

  DELETE很简单通晓。它被用来根据U陆风X8I标识删除财富。

  例如:

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

  当删除成功时,重临HTTP状态码200(表示正确),同时会顺手3个响应体body,body中也许含有了除去项的数量(这会占用部分网络带宽),只怕封装的响应(参见上面的再次来到值)。也得以回到HTTP状态码204(表示无内容)表示没有响应体。由此可见,能够回来状态码204象征不曾响应体,大概重返状态码200并且附带JSON风格的响应体。

  依照HTTP规范,DELETE操作是幂等的。尽管您对八个能源拓展DELETE操作,财富就被移除了。在财富上频繁调用DELETE最后致使的结果都无异:即财富被移除了。但假如将DELETE的操功效于计数器(能源内部),则DETELE将不再是幂等的。如前方所述,只要数据没有被更新,总括和衡量的用法照旧可被认为是幂等的。建议非幂等性的资源请求使用POST操作。

  但是,那里有2个有关DELETE幂等性的警戒。在一个能源上第一回调用DELETE往往会回到404(未找到),因为该能源已经被移除了,所以找不到了。那使得DELETE操作不再是幂等的。若是财富是从数据库中删除而不是被略去地方统一标准记为除去,那种气象供给体面妥协。

  下表总括出了第2HTTP的法门和能源UHavalI,以及推荐的重返值:

HTTP请求

/customers

/customers/{id}

GET

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

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

PUT

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

200(正确)或204(无内容)。假若没有找到ID或ID无效则赶回404(未找到)。

POST

201(创立),带有链接到/customers/{id}的职分头新闻,包蕴新的ID。

404(未找到)

DELETE

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

200(正确)。若是没有找到ID或ID无效则赶回404(未找到)。

 

DELETE

  DELETE很容易理解。它被用来根据UENCOREI标识删除能源。

  例如:

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

  当删除成功时,再次回到HTTP状态码200(表示正确),同时会顺便3个响应体body,body中恐怕带有了删除项的数目(那会占用部分互连网带宽),可能封装的响应(参见下边包车型地铁再次来到值)。也得以回来HTTP状态码204(表示无内容)表示一向不响应体。同理可得,能够回去状态码204意味从没响应体,恐怕再次回到状态码200并且附带JSON风格的响应体。

  依照HTTP规范,DELETE操作是幂等的。如果你对一个财富实行DELETE操作,能源就被移除了。在财富上屡次调用DELETE最终促成的结果都平等:即能源被移除了。但万一将DELETE的操效率于计数器(能源内部),则DETELE将不再是幂等的。如前方所述,只要数据尚未被更新,总括和度量的用法照旧可被认为是幂等的。建议非幂等性的能源请求使用POST操作。

  不过,那里有3个有关DELETE幂等性的警示。在一个财富上第③遍调用DELETE往往会重返404(未找到),因为该财富已经被移除了,所以找不到了。那使得DELETE操作不再是幂等的。假如能源是从数据库中除去而不是被总结地方统一标准记为除去,这种情景需求适宜妥协。

  下表计算出了重在HTTP的章程和财富URubiconI,以及引进的重返值:

HTTP请求

/customers

/customers/{id}

GET

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

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

PUT

404(未找到),除非你想在全体集合中更新/替换种种能源。

200(正确)或204(无内容)。如若没有找到ID或ID无效则赶回404(未找到)。

POST

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

404(未找到)

DELETE

404(未找到),除非您想删除全体集合——经常不被允许。

200(正确)。要是没有找到ID或ID无效则赶回404(未找到)。

 

能源命名

  除了适当地选择HTTP动词,在成立1个能够清楚的、易于使用的Web服务API时,能源命名能够说是最富有争议和最关键的定义。一个好的财富命名,它所对应的API看起来更直观并且易于使用。相反,倘诺命名倒霉,同样的API会令人觉得很愚笨并且难以明白和利用。当你须要为您的新API创立财富UQX56L时,那里有局地小技巧值得借鉴。

  从实质上讲,一个RESTFul
API最后都得以被总结地看成是一堆U陆风X8I的汇聚,HTTP调用那么些U科雷傲I以及部分用JSON和(或)XML表示的财富,它们中有为数不少带有了相互关系的链接。RESTful的可寻址能力主要借助URAV4I。各样财富都有自己的地方或U大切诺基I——服务器能提供的每三个行之有效的新闻都得以作为财富来公开。统一接口的规则部分地由此U路虎极光I和HTTP动词的整合来消除,并符合利用专业和预订。

  在决定你系统中要选用的能源时,使用名词来定名这几个财富,而不是用动词或动作来命名。换句话说,一个RESTful
URAV4I应该提到到一个切实可行的能源,而不是事关到一个动作。此外,名词还享有部分动词没有的习性,那也是另三个分明的要素。

  一些财富的例子:

  • 系统的用户
  • 学员注册的学科
  • 多个用户帖子的岁月轴
  • 关怀别的用户的用户
  • 一篇有关骑马的篇章

  服务套件中的每一种能源最少有八个UOdysseyI来标识。即便那些U奥迪Q3I能表示一定的含义并且能够丰盛描述它所代表的能源,那么它正是一个最棒的命名。UQX56I应该拥有可预测性和分层结构,那将推进拉长它们的可领悟性和可用性的:可预测指的是能源应该和称号保持一致;而分层指的是数码颇具关系上的组织。那并非REST规则或规范,可是它加重了对API的概念。

  RESTful
API是提需要消费端的。U路虎极光I的称呼和社团应该将它所发挥的含义传达给消费者。平常大家很难领悟数码的边际是怎么,然则从您的数量上您应有很有大概去尝试找到要赶回给客户端的数码是何等。API是为客户端而安顿的,而不是为你的数额。

  借使大家未来要描述一个囊括客户、订单,列表项,产品等成效的订单系统。考虑一下大家该怎么来描述在这一个服务中所涉及到的能源的UPRADOIs:

财富命名

  除了适当地使用HTTP动词,在开创1个能够通晓的、易于使用的Web服务API时,能源命名能够说是最具有争议和最要害的概念。2个好的能源命名,它所对应的API看起来更直观并且易于使用。相反,借职分名不佳,同样的API会令人深感很鸠拙并且难以通晓和动用。当您必要为您的新API创立财富U帕杰罗L时,那里有一些小技巧值得借鉴。

  从实质上讲,一个RESTFul
API最终都能够被归纳地看成是一堆UEvoqueI的联谊,HTTP调用这几个UXC90I以及部分用JSON和(或)XML表示的财富,它们中有许多包括了互相关联的链接。RESTful的可寻址能力根本借助UXC60I。各类财富都有温馨的地方或U奥迪Q5I——服务器能提供的各类得力的音信都得以视作财富来公开。统一接口的条件部分地因而U本田CR-VI和HTTP动词的三结合来化解,并符合利用正式和预约。

  在决定你系统中要动用的能源时,使用名词来定名这个财富,而不是用动词或动作来命名。换句话说,二个RESTful
UEscortI应该提到到二个现实的财富,而不是关系到2个动作。其余,名词还富有局地动词没有的属性,那也是另3个斐然的要素。

  一些财富的例子:

  • 系统的用户
  • 学员登记的学科
  • 三个用户帖子的日子轴
  • 尊敬入微其余用户的用户
  • 一篇有关骑马的文章

  服务套件中的每一种能源最少有1个U奇骏I来标识。假若这些ULANDI能表示肯定的意思并且能够丰盛描述它所代表的财富,那么它正是3个最佳的命名。U宝马7系I应该具有可预测性和支行结构,这将促进加强它们的可掌握性和可用性的:可预测指的是财富应该和称号保持一致;而分层指的是多少有所关系上的组织。那并非REST规则或专业,可是它加重了对API的定义。

  RESTful
API是提要求消费端的。U帕杰罗I的名称和组织应当将它所发挥的意思传达给消费者。日常大家很难掌握数据的分界是何等,然而从您的数目上你应当很有只怕去尝试找到要回来给客户端的数额是什么。API是为客户端而布署的,而不是为你的多少。

  假如大家明天要描述2个囊括客户、订单,列表项,产品等效用的订单系统。考虑一下我们该如何来讲述在这些服务中所涉及到的财富的UMuranoIs:

资源URI示例

  为了在系统中插入(创立)多个新的用户,我们能够使用:

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

 

  读取编号为33245的用户新闻:

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

  使用PUT和DELETE来请求相同的U牧马人I,能够立异和删除数据。

 

  上面是对产品有关的U奥迪Q5I的有些建议:

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

  用于创设新的制品。

 

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

  分别用于读取、更新、删除编号为66432的成品。

 

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

  一种方案是:

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

  那种方法得以用来创设订单,但缺少相应的用户数量。

  

  因为大家想为用户成立2个订单(注意之间的涉嫌),这些U普拉多I恐怕不够直观,上边这些U纳瓦拉I则更清楚一些:

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

  现在大家明白它是为编号33245的用户成立3个订单。

 

  那下边这一个请求重临的是什么样啊?

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

  恐怕是2个编号为33245的用户所成立或具备的订单列表。注意:我们能够遮挡对该URI举行DELETE或PUT请求,因为它的操作对象是二个汇聚。

 

  继续深刻,那上边这些U帕杰罗I的伸手又象征怎么着呢?

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

  大概是(为编号33245的用户)扩充二个编号为8769的订单条目。没错!假设选用GET方式呼吁这一个U酷威I,则会重临那些订单的享有条条框框。然而,如若这一个条款与用户音讯非亲非故,我们将会提供POST
www.example.com/orders/8769/lineitems
这个URI。

  从重返的那个条款来看,钦命的财富只怕会有三个U君越Is,所以我们或许也急须求提供这么二个UENVISIONI
GET
http://www.example.com/orders/8769
,用来在不通晓用户ID的场合下基于订单ID来询问订单。

 

  更进一步:

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

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

  未来你应该理解什么是分层构造了。它们并不是严俊的条条框框,只是为着确认保障在你的劳务中那么些强制的布局能够更便于被用户所驾驭。与持有软件开发中的技能一样,命名是打响的机要。

  

  多看有个别API的以身作则并学会控制那个技术,和你的队友一起来完善你API财富的UXC90Is。那里有一部分APIs的例证:

资源URI示例

  为了在系统中插入(制造)1个新的用户,大家得以选取:

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

 

  读取编号为33245的用户消息:

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

  使用PUT和DELETE来请求相同的U奇骏I,能够革新和删除数据。

 

  上边是对产品有关的U凯雷德I的某些提出:

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

  用于创造新的制品。

 

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

  分别用于读取、更新、删除编号为66432的成品。

 

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

  一种方案是:

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

  那种艺术得以用来创设订单,但贫乏相应的用户数据。

  

  因为大家想为用户创造一个订单(注意之间的涉嫌),那么些URAV4I也许不够直观,下边那一个UTiggoI则更鲜飞鹤些:

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

  今后大家了然它是为编号33245的用户创立三个订单。

 

  那上面这么些请求重返的是如何啊?

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

  或者是1个号码为33245的用户所成立或享有的订单列表。注意:大家能够遮挡对该U奇骏I进行DELETE或PUT请求,因为它的操作对象是1个会合。

 

  继续深刻,那下边那个U中华VI的乞求又象征怎么样呢?

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

  也许是(为编号33245的用户)增添3个号码为8769的订单条目。没错!即使应用GET情势呼吁这一个UTiguanI,则会再次回到那个订单的有所条条框框。不过,若是那个条款与用户新闻非亲非故,大家将会提供POST
www.example.com/orders/8769/lineitems
这个URI。

  从重返的这几个条款来看,钦赐的能源或许会有多个URubiconIs,所以大家也许也必要要提供这么3个ULANDI
GET
http://www.example.com/orders/8769
,用来在不精晓用户ID的图景下基于订单ID来询问订单。

 

  更进一步:

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

  可能只回去同个订单中的第一个条款。

  未来你应当通晓什么是分层协会了。它们并不是严谨的条条框框,只是为着有限支撑在你的劳动中这一个强制的布局能够更便于被用户所知道。与具有软件开发中的技能一样,命名是打响的根本。

  

  多看有个别API的以身作则并学会控制这个技能,和你的队友一起来宏观你API财富的URubiconIs。这里有部分APIs的事例:

财富命名的反例

  前边我们曾经切磋过部分适合的财富命名的例子,可是有时一些反面包车型客车例证也很有教育意义。下面是部分不太具有RESTful风格的财富U冠道Is,看起来比较散乱。这几个都以荒谬的例子! 

  首先,一些serivices往往选取单一的U福睿斯I来钦命服务接口,然后经过询问参数来钦赐HTTP请求的动作。例如,要立异编号12345的用户消息,带有JSON
body的呼吁恐怕是如此:

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

  就算位置U奥迪Q5L中的”services”的那些节点是一个名词,但那个U帕杰罗L不是自解释的,因为对此有着的伏乞而言,该U劲客I的层级结构都以同等的。别的,它利用GET作为HTTP动词来施行二个翻新操作,那简直正是反人类(甚至是惊险的)。

  上面是此外3个更新用户的操作的事例:

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

  以及它的3个变种:

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

  你会时常见到在其它开发者的劳务套件中有诸多那样的用法。能够看看,那么些开发者试图去创设RESTful的财富名称,而且已经有了一些升华。不过你照样能够分辨出URAV4L中的动词短语。注意,在这几个UEnclaveL中大家不要求”update”那些词,因为大家能够借助HTTP动词来形成操作。上边那一个U途乐L正好表明了这点:

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

  这些请求同时设有PUT和”update”,那会对顾客产生迷惑!那里的”update”指的是四个能源吗?因而,这里大家费些口舌也是梦想你可以通晓……

财富命名的反例

  前面大家早已探究过部分适中的能源命名的例子,可是有时一些反面包车型地铁例证也很有教育意义。上面是局地不太具有RESTful风格的财富U中华VIs,看起来比较混乱。那个都是不对的例证! 

  首先,一些serivices往往采纳单一的U奥迪Q7I来内定服务接口,然后通过查询参数来钦命HTTP请求的动作。例如,要创新编号12345的用户音信,带有JSON
body的请求大概是那般:

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

  就算地点U翼虎L中的”services”的那几个节点是1个名词,但以此U奇骏L不是自解释的,因为对于具有的呼吁而言,该U兰德锐界I的层级结构都是一样的。另外,它选择GET作为HTTP动词来进行一个翻新操作,那大致正是反人类(甚至是摇摇欲坠的)。

  下边是此外贰个更新用户的操作的事例:

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

  以及它的3个变种:

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

  你会时不时来看在别的开发者的劳务套件中有许多那样的用法。能够见见,这个开发者试图去创立RESTful的财富名称,而且早已有了某些前行。不过你还是能够辨识出UXC60L中的动词短语。注意,在那一个U奥迪Q5L中大家不必要”update”那么些词,因为我们得以凭借HTTP动词来形成操作。下边那一个UPRADOL正好表明了那一点:

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

  那几个请求同时设有PUT和”update”,那会对顾客发生迷惑!这里的”update”指的是1个财富吗?因而,那里我们费些口舌也是梦想您可见精通……

复数

  让大家来研商一下复数和“单数”的争议…还没传说过?但那种争议确实存在,事实上它能够归咎为那些难点……

  在你的层级结构中U冠道I节点是不是供给被取名为单数或复数格局吗?举个例证,你用来寻觅用户财富的U福特ExplorerI的命名是还是不是要求像上边那样:

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

  或者:

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

  三种方法都没难题,但常见咱们都会选择选择复数命名,以使得你的API
U逍客I在拥有的HTTP方法中保持一致。原因是根据那样一种考虑:customers是劳务套件中的三个会晤,而ID33245的这几个用户则是其一集合中的当中贰个。

  根据这些规则,贰个用到复数情势的多节点的U途锐I会是这般(注意粗体部分):

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

  “customers”、“orders”以及“lineitems”那么些U索罗德I节点都利用的是复数格局。

  那代表你的各类根能源只供给四个主导的UEscortL就足以了,2个用以成立集合内的能源,另一个用来依据标识符获取、更新和删除能源。例如,以customers为例,创制能源能够使用上边包车型客车UXC90L进行操作:

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

  而读取、更新和删除能源,使用上边包车型地铁U安德拉L操作:

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

  正如前方提到的,给定的能源可能有八个U奥德赛I,但作为三个十分小的总体的增加和删除改查功用,利用七个简单的U途锐I来处理就够了。

  恐怕你会问:是还是不是在有点意况下复数没有意义?嗯,事实上是如此的。当没有集合概念的时候(此时复数没有意义)。换句话说,当财富唯有1个的情况下,使用单数财富名称也是足以的——即3个十足的财富。例如,要是有二个单纯的全部布置能源,你能够使用贰个单数名称来表示:

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

  注意那里缺乏configuration的ID以及HTTP动词POST的用法。如果种种用户有三个配置来说,那么这些U牧马人L会是如此:

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

  同样让人瞩目那里没有点名configuration的ID,以及没有给定POST动词的用法。在这多个例证中,也许也会有人以为利用POST是立竿见影的。好吧…

 

复数

  让大家来切磋一下复数和“单数”的争持…还没据说过?但那种争议确实存在,事实上它能够归纳为那一个题目……

  在您的层级结构中ULacrosseI节点是或不是必要被命名为单数或复数情势呢?举个例证,你用来寻找用户财富的ULX570I的命名是还是不是需求像下边那样:

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

  或者:

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

  二种办法都没难点,但平常我们都会选拔选拔复数命名,以使得你的API
U昂CoraI在具备的HTTP方法中保持一致。原因是依照那样一种考虑:customers是服务套件中的贰个集合,而ID33245的这一个用户则是这几个集合中的个中二个。

  根据那几个规则,1个施用复数情势的多节点的ULX570I会是那样(注意粗体部分):

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

  “customers”、“orders”以及“lineitems”这几个UTiguanI节点都使用的是复数格局。

  那意味着你的各种根能源只需求多个为主的U本田UR-VL就能够了,三个用于创建集合内的财富,另一个用来依据标识符获取、更新和删除财富。例如,以customers为例,创建财富得以行使上边包车型地铁U瑞虎L举办操作:

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

  而读取、更新和删除能源,使用上边包车型大巴U安德拉L操作:

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

  正如前方提到的,给定的能源只怕有八个U逍客I,但作为2个微小的全体的增加和删除改查功用,利用三个简易的UTiguanI来处理就够了。

  或然你会问:是或不是在有个别情状下复数没有意义?嗯,事实上是那般的。当没有集合概念的时候(此时复数没有意义)。换句话说,当财富唯有三个的情况下,使用单数财富名称也是能够的——即贰个单纯的财富。例如,假设有三个单一的完好布局财富,你能够运用3个单数名称来表示:

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

  注意那里缺乏configuration的ID以及HTTP动词POST的用法。假若每一个用户有2个安排来说,那么这些U奥德赛L会是如此:

  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”。

  通过那种措施,在U奥迪Q5I中钦点重返表征的格式,能够增加U奥迪Q3L的可知性。例如,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
404的一无所能。

  使用HTTP
Accept头被周边认为是一种更优雅的艺术,并且符合HTTP的正儿八经和意义,客户端能够因此那种措施来报告HTTP服务端它们可扶助的数据类型有哪些。不过,为了选用Accept头,服务端要同时扶助封装和未封装的响应,你必须完结自定义的类型——因为这几个格式不是规范的门类。那大大增添了客户端和服务端的复杂性。请参见宝马7系FC
2616的14.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纳瓦拉I中钦点重临表征的格式,能够增强URAV4L的可知性。例如,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格式的能源,将回来1个HTTP
404的一无所能。

  使用HTTP
Accept头被大规模认为是一种更优雅的方法,并且符合HTTP的正规和含义,客户端能够透过那种艺术来告诉HTTP服务端它们可支撑的数据类型有啥样。但是,为了选取Accept头,服务端要同时扶助封装和未封装的响应,你不能够不达成自定义的门类——因为那一个格式不是规范的门类。这大大扩展了客户端和服务端的复杂。请参见HavalFC
2616的14.1节关于Accept头的详细音讯(http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1)。使用文件扩大名来钦赐数量格式是最简便易行直接的办法,用最少的字符就足以做到,并且支持脚本操作——无需使用HTTP头。

  平日当大家提到REST服务,跟XML是无关的。尽管服务端辅助XML,也大约没有人提议在REST中应用XML。XML的正经和公约在REST中不太适用。特别是它连命名空间都尚未,就更不应该在RESTful服务种类中采纳了。这只会使工作变得更复杂。所以回来的XML看起来更像JSON,它大约易读,没有形式和命名空间的限量,换句话来说是无标准的,易于解析。

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

  REST辅导规范之一(依照联合接口规范)是application的事态通过hypertext(超文本)来传输。那就是我们司空眼惯所说的Hypertext
As The Engine of Application State
(即HATEOAS,用超文本来作为应用程序状态机),大家在“REST是什么”一节中也提到过。

  依据罗伊Fielding在他的博客中的描述(http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertextdriven),REST接口中最重点的片段是超文本的运用。其它,他还提出,在交付任何相关的新闻在此以前,一个API应该是可用和可见晓的。也便是说,叁个API应当能够通过其链接导航到数量的依次部分。不提出只回去纯数据。

  然则当下的产业界先驱们并从未常常应用那种做法,那反映了HATEOAS仅仅在成熟度模型中的使用率更高。纵观众多的服务种类,它们基本上重回更加多的数额,而回到的链接却很少(恐怕没有)。那是违反Fielding的REST约定的。菲尔德ing说:“新闻的每三个可寻址单元都指点二个地方……查询结果应当显示为一个富含摘要消息的链接清单,而不是指标数组。”

  另一方面,不难凶恶地将全体链接集合重临会大大影响网络带宽。在事实上情状中,依照所需的标准或应用境况,API接口的通讯量要依照服务器响应中中国足球球组织一流联赛文本链接所包含的“摘要”数量来抵消。

  同时,丰硕利用HATEOAS可能会增多落成的纷纭,并对劳务客户端产生明显的负担,这一定于下跌了客户端和服务器端开发人士的生产力。因而,当务之急是要平衡超链接服务实践和水保可用能源之间的题材。

  超链接最小化的做法是在最大限度地减小客户端和服务器之间的耦合的同时,升高服务端的可用性、可操纵性和可驾驭性。那几个最小化建议是:通过POST成立能源并从GET请求重临集合,对于有分页的场日前边大家会波及。

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

  REST教导原则之一(根据联合接口规范)是application的事态通过hypertext(超文本)来传输。那正是我们层见迭出所说的Hypertext
As The Engine of Application State
(即HATEOAS,用超文本来作为应用程序状态机),我们在“REST是什么”一节中也涉嫌过。

  依照罗伊Fielding在她的博客中的描述(http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertextdriven),REST接口中最要害的局地是超文本的选取。其余,他还提出,在提交任何相关的音信在此以前,多少个API应该是可用和可分晓的。也便是说,3个API应当能够透过其链接导航到数码的逐条部分。不提议只回去纯数据。

  然则当下的产业界先驱们并不曾常常选用那种做法,那呈现了HATEOAS仅仅在成熟度模型中的使用率更高。纵观者多的服务连串,它们基本上再次回到愈多的数额,而回到的链接却很少(只怕没有)。那是反其道而行之Fielding的REST约定的。Fielding说:“新闻的每2个可寻址单元都引导3个地址……查询结果应当展现为1个分包摘要新闻的链接清单,而不是目的数组。”

  另一方面,简单狠毒地将全部链接集合重临会大大影响网络带宽。在骨子里情状中,依照所需的原则或选拔状态,API接口的通讯量要依照服务器响应中中国足球球组织一级联赛文本链接所包蕴的“摘要”数量来平衡。

  同时,丰裕利用HATEOAS大概会追加实现的繁杂,并对服务客户端发生明显的承受,这一定于下落了客户端和劳务器端开发人士的生产力。因此,当务之急是要平衡超链接服务实施和水保可用财富之间的标题。

  超链接最小化的做法是在最大限度地减小客户端和服务器之间的耦合的同时,升高服务端的可用性、可操纵性和可通晓性。这几个最小化指出是:通过POST创制财富并从GET请求再次回到集合,对于有分页的场地后边大家会涉及。

小小化链接推荐

  在create的用例中,新建财富的U景逸SUVI(链接)应该在Location响应头中回到,且响应中央是空的——只怕只包涵新建财富的ID。

  对于从服务端重回的特色集合,每一种表征应该在它的链接集合中带走3个相当的小的“本人”链接属性。为了便利分页操作,其余的链接能够置身贰个独自的链接集合中回到,须要时得以分包“第二页”、“上一页”、“下一页”、“最终一页”等音讯。

  参照下文链接格式部分的事例获取越来越多音讯。

小小的化链接推荐

  在create的用例中,新建财富的U哈弗I(链接)应该在Location响应头中回到,且响应中央是空的——可能只含有新建财富的ID。

  对于从服务端再次回到的性状集合,各样表征应该在它的链接集合中教导三个细微的“自己”链接属性。为了方便分页操作,其余的链接能够放在1个独自的链接集合中回到,须求时方可包括“第③页”、“上一页”、“下一页”、“最终一页”等新闻。

  参照下文链接格式一对的例证获取越多音讯。

链接格式

  参照整个链接格式的正式,建议遵循一些近乎Atom、AtomPub或Xlink的品格。JSON-LD也不利,但并从未被大面积采用(假如已经被用过)。近日标准最广大的法门是行使含有”rel”成分和含有财富全部U君越I的”href”成分的Atom链接格式,不分包别的身份验证或询问字符串参数。”rel”成分得以分包标准值”alternate”、”related”、”self”、”enclosure”和”via”,还有分页链接的“第①页”、“上一页”、“下一页”,“最终一页”。在要求时方可自定义并累加应用它们。

  一些XML
Atom格式的定义对于用JSON格式表示的链接来说是没用的。例如,METHOD属性对于三个RESTful能源来说是不须求的,因为对于一个加以的财富,在全数援助的HTTP方法(CRUD行为)中,财富的U奥迪Q5I都是一模一样的——所以单独列出这一个是未曾要求的。

  让大家举一些具体的事例来更为印证那或多或少。上面是调用创造新能源的请求后的响应:

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

  上边是响应头集合中包括成立新能源的UOdysseyI的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请求获取一个富含分页的特征集合的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集合中的每一项都含有一个针对性“本人(self)”的链接。那里或者还会有部分涉嫌到集结的其余链接,但都与分页本身非亲非故。简单的说,那里有三个地点含有links。一个正是data对象中所蕴含的汇集(这些也是接口要回到给客户端的数目表征集合),在那之中的每一项至少要包蕴二个针对性“本身(self)”的links集合;另三个则是几个单独的目的links,个中包括和分页相关的链接,该片段的始末适用于任何集合。

  对于经过POST请求创制能源的动静,要求在响应头中包罗八个涉嫌新建对象链接的Location

链接格式

  参照整个链接格式的正经,建议遵从一些近似Atom、AtomPub或Xlink的作风。JSON-LD也不错,但并不曾被大规模运用(假使已经被用过)。近期正式最普遍的章程是选择带有”rel”成分和富含能源总体URI的”href”成分的Atom链接格式,不包涵其余身份验证或询问字符串参数。”rel”成分得以包罗标准值”alternate”、”related”、”self”、”enclosure”和”via”,还有分页链接的“第①页”、“上一页”、“下一页”,“最终一页”。在要求时得以自定义并加上应用它们。

  一些XML
Atom格式的定义对于用JSON格式表示的链接来说是没用的。例如,METHOD属性对于二个RESTful能源来说是不须求的,因为对于3个加以的财富,在颇具帮忙的HTTP方法(CRUD行为)中,能源的U帕杰罗I都以相同的——所以单独列出那几个是未曾须要的。

  让大家举一些切实可行的事例来尤其评释这点。下边是调用创造新财富的乞求后的响应:

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

  上面是响应头集合中含有创设新能源的URubiconI的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能够为空,可能隐含3个被卷入的响应(见下文封装响应)。

  上边包车型客车例证通过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数组中的每一项都带有三个对准“自个儿(self)”的链接。该数组还大概还含有其余关系,如children、parent等。

  最终3个事例是由此GET请求获取一个带有分页的特征集合的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集合中的每一项都包罗贰个针对性“本身(self)”的链接。那里恐怕还会有部分提到到聚集的其它链接,但都与分页自己非亲非故。简单的说,那里有五个地点含有links。二个正是data对象中所包括的集合(这些也是接口要赶回给客户端的数目表征集合),当中的每一项至少要包蕴一个针对性“本身(self)”的links集合;另2个则是多个单独的指标links,个中包涵和分页相关的链接,该片段的始末适用于任何集合。

  对于经过POST请求创制能源的气象,须求在响应头中包括多个涉嫌新建对象链接的Location

包裹响应

   服务器可以在响应中同时再次回到HTTP状态码和body。有好多JavaScript框架没有把HTTP状态响应码重回给最后的开发者,那频仍会导致客户端不可能依据气象码来明确具体的一颦一笑。其余,即使HTTP规范中有很四种响应码,可是频仍只有个别客户端会关注那么些——日常我们只在乎”success”、”error”或”failture”。因而,将响应内容和响应状态码封装在富含响应新闻的特征中,是有要求的。

  OmniTI
实验室有那样2个建议,它被称作JSEND响应。更加多音讯请参见http://labs.omniti.com/labs/jsend。别的多少个提案是由DouglasCrockford提议的,能够查看那里http://www.json.org/JSONRequest.html

  那一个提案在实践中并从未完全涵盖全数的意况。基本上,今后最棒的做法是根据以下属性封装常规(非JSONP)响应:

  • code——包涵2个整数类其余HTTP响应状态码。
  • status——包蕴文本:”success”,”fail”或”error”。HTTP状态响应码在500-599以内为”fail”,在400-499以内为”error”,其余均为”success”(例如:响应状态码为1XX、2XX和3XX)。
  • message——当状态值为”fail”和”error”时有效,用于浮现错误消息。参照国际化(il8n)标准,它能够包涵音讯号或然编码,能够只包括当中多个,大概同时富含并用分隔符隔离。
  • 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>

打包响应

   服务器能够在响应中还要重返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——蕴含一个平头项指标HTTP响应状态码。
  • status——包蕴文本:”success”,”fail”或”error”。HTTP状态响应码在500-599里边为”fail”,在400-499里边为”error”,别的均为”success”(例如:响应状态码为1XX、2XX和3XX)。
  • message——当状态值为”fail”和”error”时有效,用于显示错误音讯。参照国际化(il8n)标准,它可以分包音讯号大概编码,能够只含有在那之中2个,或许同时涵盖并用分隔符隔离。
  • data——包涵响应的body。当状态值为”fail”或”error”时,data仅包涵错误原因或尤其名称。

  上边是2个回去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宝马7系S)。JSONP或“填充的JSON”是一种接纳方式,它提供了3个措施请求来自差别域中的服务器的数据。其工作章程是从服务器重临任意的JavaScript代码,而不是JSON。客户端的响应由JavaScript解析器实行分析,而不是直接解析JSON数据。其它,CO帕杰罗S是一种web浏览器的技能专业,它为web服务器定义了一种艺术,从而允许服务器的财富得以被不一致域的网页访问。COLacrosseS被当做是JSONP的新星替代品,并且能够被抱有现代浏览器帮忙。因而,不建议利用JSONP。任何境况下,推荐采纳CO卡宴S。

拍卖跨域难点

   大家都闻讯过关于浏览器的同源策略或同源性需要。它指的是浏览器只可以请求当前正值展现的站点的财富。例如,如果当前正在显示的站点是www.Example1.com,则该站点不能够对www.Example.com提倡呼吁。显著那会潜移默化站点访问服务器的艺术。

  近来有七个被大面积接受的扶助跨域请求的法门:JSONP和跨域财富共享(CO揽胜极光S)。JSONP或“填充的JSON”是一种选取格局,它提供了三个主意请求来自差别域中的服务器的数据。其行事章程是从服务器重临任意的JavaScript代码,而不是JSON。客户端的响应由JavaScript解析器实行解析,而不是一向解析JSON数据。别的,CO哈弗S是一种web浏览器的技术专业,它为web服务器定义了一种办法,从而允许服务器的财富能够被分裂域的网页访问。CO奥迪Q5S被看成是JSONP的摩登替代品,并且能够被有着现代浏览器支持。由此,不建议利用JSONP。任何动静下,推荐选择COPRADOS。

支持CORS

  在服务端完结COLacrosseS相当粗略,只需求在出殡和埋葬响应时顺便HTTP头,例如: 

Access-Control-Allow-Origin: *

  唯有在数据是集体使用的状态下才会将造访来源设置为”*”。超越四分之一景观下,Access-Control-Allow-Origin头应该钦定哪些域能够发起2个COPRADOS请求。唯有要求跨域访问的UPAJEROL才设置CORAV4S头。

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/

支持CORS

  在服务端完毕COHavalS相当粗略,只要求在发送响应时顺便HTTP头,例如: 

Access-Control-Allow-Origin: *

  只有在数量是集体使用的图景下才会将造访来源设置为”*”。超越47%景观下,Access-Control-Allow-Origin头应该钦命哪些域能够发起四个COPAJEROS请求。唯有需求跨域访问的U君越L才设置CORS头。

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服务器、代理来展开布局,恐怕从服务器本身发送。不推荐在服务端达成,因为很不灵活。或许,能够运用方面的第1种方法,在web服务器上配置二个用空格分隔的域的列表。更多关于CO宝马X5S的内容能够参照那里:http://enable-cors.org/

支持JSONP

  JSONP通过采取GET请求避开浏览器的界定,从而实现对富有服务的调用。其行事原理是请求方在伸手的U瑞虎L上添加贰个字符串查询参数(例如:jsonp=”jsonp_callback”),当中“jsonp”参数的值是JavaScript函数名,该函数在有响应再次来到时将会被调用。

  由于GET请求中没有包涵请求体,JSONP在应用时有着严重的局限性,由此数据必须透过字符串查询参数来传递。同样的,为了帮衬PUT,POST和DELETE方法,HTTP方法必须也通过字符串查询参数来传递,类似_method=POST那种样式。像那样的HTTP方法传送方式是不引进应用的,那会让服务处于安全危害之中。

  JSONP日常在局部不扶助COTiggoS的老旧浏览器中选用,假如要改成帮助CO福睿斯S的,会影响总体服务器的架构。或然大家也足以透过代办来促成JSONP。同理可得,JSONP正在被CORAV4S所取代,大家应该尽大概地选拔COSportageS。

  为了在服务端帮衬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请求避开浏览器的范围,从而落成对负有服务的调用。其行事原理是请求方在乞请的UCRUISERL上添加叁个字符串查询参数(例如:jsonp=”jsonp_callback”),当中“jsonp”参数的值是JavaScript函数名,该函数在有响应重回时将会被调用。

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

  JSONP平时在有个别不帮忙COPRADOS的老旧浏览器中使用,倘使要改成帮衬CO奥迪Q5S的,会潜移默化全部服务器的架构。恐怕大家也得以透过代办来落到实处JSONP。综上说述,JSONP正在被CO中华VS所取代,大家应有尽恐怕地运用COXC60S。

  为了在服务端帮衬JSONP,在JSONP字符串查询参数字传送递时,响应必要求实施以下这几个操作:

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

  其它,响应体中时常必须带有响应头。那使得JSONP回调方法要求基于响应体来规定响应处理格局,因为它本人无法获知真实的响应头和境况值。

  上面的例子是安份守己上述情势封装的3个赶回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处理的角度来看,限制数据量也同等相当重要,因为UI常常只好显示大数量集中的一小部分多少。在数据集的增速不分明的图景下,限制暗许重回的数据量是很有供给的。以Facebook为例,要赢得有个别用户的推文(通过个人主页的日子轴),假使没有专门钦命,请求暗许只会回来20条记下,即便系统最多能够回去200条记下。

  除了限制再次来到的数据量,大家还必要考虑怎么着对天意据集进行“分页”或下拉滚动操作。创制数量的“页码”,重回大数目列表的已知片段,然后标出数据的“前一页”和“后一页”——这一表现被称为分页。别的,大家兴许也要求内定响应中将包罗如何字段或质量,从而限制再次回到值的多寡,并且大家期望最后能够因此特定值来展开询问操作,并对再次来到值进行排序。

  有二种主要的不二法门来还要限制查询结果和履行分页操作。首先,大家得以创造八个索引方案,它能够以页码为导向(请求中要付出每一页的记录数及页码),也许以记录为导向(请求中央直机关接交给第三条记下和末段一条记下)来明确重返值的开首地点。举个例子,那三种艺术分别代表:“给出第六页(若是每页有20条记下)的记录”,或“给出第捌0到第三20条的笔录”。

  服务端将基于运作体制来进展切分。有个别UI工具,比如Dojo
JSON会接纳模仿HTTP规范应用字节范围。假诺服务端援助out of
box(即开箱即用效应),则前端UI工具和后端服务时期无需任何转换,那样使用起来会很有益。

  下文将介绍一种艺术,既能够接济Dojo那样的分页格局(在请求头中提交记录的限制),也能支撑采用字符串查询参数。这样一来服务端将变得尤其灵活,既能够利用类似Dojo一样先进的UI工具集,也得以选拔简易直接的链接和标签,而无需再为此扩大复杂的开发工作。但要是服务不直接扶助UI成效,可以考虑不要在请求头中付出记录范围。

  要专门提出的是,大家并不推荐在享有服务中动用查询、过滤和分页操作。并不是兼具能源都暗许协助那一个操作,只有少数特定的财富才支撑。服务和资源的文书档案应当表达什么接口帮忙那一个纷纭的功用。

询问,过滤和分页

  对于大数据集,从带宽的角度来看,限制重临的数据量是不行主要的。而从UI处理的角度来看,限制数据量也同等十分重要,因为UI常常只好彰显大数据汇总的一小部分数据。在数据集的增速不鲜明的状态下,限制暗中认可重回的数据量是很有必不可少的。以推特为例,要获取有个别用户的推文(通过个人主页的年华轴),如若没有特意内定,请求暗中认可只会重临20条记下,就算系统最多能够回来200条记下。

  除了限制重回的数据量,大家还亟需考虑什么对命局据集进行“分页”或下拉滚动操作。创制数量的“页码”,重临大数量列表的已知片段,然后标出数据的“前一页”和“后一页”——这一行事被称作分页。其它,大家大概也亟需钦点响应大校包罗怎样字段或性质,从而限制重返值的多寡,并且我们期待最终能够透过特定值来拓展询问操作,并对重临值进行排序。

  有二种重点的点子来还要限制查询结果和施行分页操作。首先,大家得以成立2个目录方案,它能够以页码为导向(请求中要付出每一页的记录数及页码),只怕以记录为导向(请求中央直机关接提交第壹条记下和尾声一条记下)来规定再次来到值的初始地点。举个例子,那两种格局分别代表:“给出第5页(若是每页有20条记下)的记录”,或“给出第⑧0到第二20条的笔录”。

  服务端将基于运作机制来进行切分。有个别UI工具,比如Dojo
JSON会采取模仿HTTP规范应用字节范围。如果服务端扶助out of
box(即开箱即用效用),则前端UI工具和后端服务中间无需任何转换,这样使用起来会很便宜。

  下文将介绍一种方式,既能够帮忙Dojo那样的分页格局(在请求头中提交记录的范围),也能支撑选取字符串查询参数。那样一来服务端将变得更为灵敏,既能够采纳类似Dojo一样先进的UI工具集,也得以使用简易直接的链接和标签,而无需再为此扩张复杂的支付工作。但万一服务不直接帮助UI功用,能够考虑不要在请求头中提交记录范围。

  要尤其提出的是,大家并不引进在有着服务中采取查询、过滤和分页操作。并不是有着能源都默许协理这个操作,唯有某个特定的能源才支撑。服务和能源的文书档案应当表达什么接口帮忙那个纷纷的机能。

结果限制

  “给出第一到第陆5条的笔录”,那种请求数据的办法和HTTP的字节范围规范更平等,由此大家得以用它来标识Range
header。而“从第1条记下起头,给出最多20条记下”那种格局更易于阅读和通晓,因此大家一般会用字符串查询参数的方式来表示。

  综上所述,推荐既协助选用HTTP Range
header,也支撑选用字符串查询参数——offset(偏移量)和limit(限制),然后在服务端对响应结果开始展览限定。注意,假若同时扶助那二种方法,那么字符串查询参数的先行级要压倒Range
header。

  那里您可能会有个问号:“那三种方法效果相似,但是回到的数量不完全一致。那会不会令人歪曲呢?”恩…那是四个难点。首先要应对的是,那着实会让人歪曲。关键是,字符串查询参数看起来更为清晰易懂,在营造和剖析时越发有益于。而Range
header则越多是由机器来行使(偏向于底层),它越是吻合HTTP使用正式。

  总而言之,解析Range
header的工作会扩展复杂度,相应的客户端在创设请求时也需求举办部分拍卖。而选择单独的limit和offset参数会越来越便于通晓和营造,并且不须求对开发人士有越来越多的需要。

结果限制

  “给出第一到第⑤5条的记录”,那种请求数据的措施和HTTP的字节范围规范更平等,由此大家能够用它来标识Range
header。而“从第3条记下开始,给出最多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多少个记录,倘若数据集中至少有25条记下。

  而在服务端,通过检查请求的Range
header来鲜明该重返哪些记录。只要Range
header存在,就会有二个总结的正则表明式(如”items=(\d+)-(\d+)”)对其展开解析,来获取要摸索的范围值。

用范围标记实行限制

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

  Range: items=0-24

  注意记录是从0开首的接连字段,HTTP规范中表明了怎么利用Range
header来请求字节。也正是说,假设要乞求数据集中的第叁条记下,范围应该从0开头算起。上述的央浼将会回来前2多少个记录,假若数据集中至少有25条记下。

  而在服务端,通过检查请求的Range
header来明确该重返哪些记录。只要Range
header存在,就会有三个归纳的正则表达式(如”items=(\d+)-(\d+)”)对其进展辨析,来博取要摸索的范围值。

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

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

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

  Offset参数的值与Range
header中的类似,也是从0开头猜度。Limit参数的值是回去记录的最大数额。当字符串查询参数中未内定limit时,服务端应当提交叁个缺省的最大limit值,但是这一个参数的运用都亟需在文书档案中举办求证。

用字符串查询参数实行限定

  字符串查询参数被看做Range
header的替代选用,它利用offset和limit作为参数名,个中offset代表要询问的率先条记下编号(与上述的用来范围标记的items第②个数字相同),limit代表记录的最大条数。上边包车型地铁事例重临的结果与上述用范围标记的例子一样:

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

  Offset参数的值与Range
header中的类似,也是从0起初揣摸。Limit参数的值是回去记录的最大数额。当字符串查询参数中未内定limit时,服务端应当交付贰个缺省的最大limit值,可是那个参数的施用都亟需在文书档案中进行表明。

依照范围的响应

  对3个依据范围的伏乞来说,无论是通过HTTP的Range
header还是经过字符串查询参数,服务端都应有有贰个Content-Range
header来响应,以标明再次回到记录的条数和总记录数:

  Content-Range: items 0-24/66

  注意那里的总记录数(如本例中的66)不是从0开端计算的。若是要央浼数据汇总的最终几条记下,Content-Range
header的剧情应该是那样:

  Content-Range: items 40-65/66

  依据HTTP的正统,若是响应时总记录数未知或难以计算,也足以用星号(”*”)来顶替(如本例中的66)。本例中响应头也可那样写:

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

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

依据范围的响应

  对3个依据范围的央求来说,无论是通过HTTP的Range
header依旧通过字符串查询参数,服务端都应有有多少个Content-Range
header来响应,以注解重返记录的条数和总记录数:

  Content-Range: items 0-24/66

  注意那里的总记录数(如本例中的66)不是从0开头计算的。假设要央求数据汇总的尾声几条记下,Content-Range
header的剧情应该是如此:

  Content-Range: items 40-65/66

  依照HTTP的正规,假若响应时总记录数未知或不便总结,也足以用星号(”*”)来顶替(如本例中的66)。本例中响应头也可那样写:

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

  可是要留意,Dojo或部分其它的UI工具恐怕不援救该符号。

分页

  上述办法经过请求方钦命数据集的限定来限制重回结果,从而达成分页功效。下面的事例中一起有66条记下,倘诺每页25条记下,要出示第贰页数据,Range
header的剧情如下:

  Range: items=25-49

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

  GET …?offset=25&limit=25

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

  Content-Range: 25-49/66

  在大部情状下,那种分页格局都没反常。但偶尔会有那种意况,便是要回来的笔录数据不能够直接表示成多少集中的行号。还有正是有个别数据集的浮动十分的快,不断会有新的数量插入到数量集中,那样自然会招致分页出现难题,一些再一次的数码也许会冒出在不一样的页中。

  按日期排列的数据集(例如Facebookfeed)正是一种普遍的情景。纵然您要么得以对数据开始展览分页,但神蹟用”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/**

分页

  上述办法经过请求方钦赐数据集的界定来界定重返结果,从而完成分页功用。上边的例证中一共有66条记下,假若每页25条记下,要来得第1页数据,Range
header的内容如下:

  Range: items=25-49

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

  GET …?offset=25&limit=25

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

  Content-Range: 25-49/66

  在大部动静下,那种分页形式都尚未难题。但偶尔会有那种情景,就是要回到的笔录数据不能间接表示成多少集中的行号。还有正是某个数据集的变迁十分的快,不断会有新的多寡插入到多少集中,那样必然会招致分页出现难点,一些重复的数量或然会出现在差别的页中。

  按日期排列的数据集(例如推特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/**

结果的过滤和排序

  针对重回结果,还索要考虑如何在服务端对数据举行过滤和排列,以及哪些按钦命的次第对子数据开始展览搜寻。那么些操作可以与分页、结果限制,以及字符串查询参数filter和sort等相结合,能够兑现强大的数据检索功用。

  再强调3回,过滤和排序都是长短不一的操作,不须要暗中同意提须要持有的能源。下文将介绍怎么样财富供给提供过滤和排序。

结果的过滤和排序

  针对重回结果,还索要考虑怎么在服务端对数码实行过滤和排列,以及哪些按钦赐的相继对子数据开始展览检索。这个操作可以与分页、结果限制,以及字符串查询参数filter和sort等相结合,可以兑现强大的数据检索作用。

  再强调一回,过滤和排序都以错综复杂的操作,不须求暗许提必要持有的财富。下文将介绍咋样能源要求提供过滤和排序。

过滤

  在本文中,过滤被定义为“通过一定的标准来鲜明必须求重回的多寡,从而减弱重回的多寡”。假使服务端帮助一套完整的可比运算符和错综复杂的规则协作,过滤操作将变得一定复杂。然而我们一般会选取部分简单的表明式,如starts-with(以…开头)或contains(包罗)来进展匹配,以保障重临数据的完整性。

  在大家初叶谈论过滤的字符串查询参数从前,必须先明白怎么要选用单个参数而不是四个字符串查询参数。从根本上来说是为了减少参数名称的争辨。我们早已有offsetlimitsort(见下文)参数了。假如大概的话还会有jsonpformat标识符,恐怕还会有afterbefore参数,那一个都以在本文中涉及过的字符串查询参数。字符串查询中央银行使的参数越来越多,就越或者引致参数名称的争持,而采取单个过滤参数则会将冲突的大概降到最低。

  其余,从服务端也很容易仅透过单个的filter参数来判断请求方是不是供给多少过滤效果。假设查询需求的复杂度扩大,单个参数将更兼具灵活性——能够协调建立一套效能一体化的询问语法(详见下文OData注释或访问http://www.odata.org)。

  通过引入一组广泛的、公认的分隔符,用于过滤的表明式能够以丰富直观的样式被采取。用那一个分隔符来设置过滤查询参数的值,这么些分隔符所创造的参数名/值对能够进一步不难地棉被和衣服务端解析并增强多少查询的质量。近期已有个别分隔符包涵用来分隔每一种过滤短语的竖线(”|”)和用来分隔参数名和值的双冒号(”::”)。那套分隔符丰盛唯一,并符合大部分气象,同时用它来创设的字符串查询参数也特别便于精晓。上面将用一个简便的事例来介绍它的用法。如果大家想要给名为“托德”的用户们发送请求,他们住在鹿特丹,有着“Grand
Poobah”之称。用字符串查询参数完结的呼吁U库罗德I如下:

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

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

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

  简单而卓有成效。有关大小写敏感的题材,要根据具体情状来看,但总的看,在毫不关切大小写的情景下,过滤效果能够很好地运作。若查询参数名/值对中的属性值未知,你也能够用星号(”*”)来代替。

  除了简单来表达式和通配符之外,若要进行更复杂的查询,你必须求引入运算符。在那种景观下,运算符本身也是属性值的一局部,能够棉被和衣服务端解析,而不是变成属性名的一片段。当供给复杂的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)。

  通过引入一组广泛的、公认的分隔符,用于过滤的表明式能够以格外直观的样式被使用。用这几个分隔符来设置过滤查询参数的值,那几个分隔符所创设的参数名/值对能够进一步便于地棉被和衣服务端解析并增强数据查询的属性。近日已有个别分隔符包蕴用来分隔每一个过滤短语的竖线(”|”)和用来分隔参数名和值的双冒号(”::”)。那套分隔符丰盛唯一,并符合超越一全场地,同时用它来创设的字符串查询参数也尤为便于领悟。上边将用二个简单易行的例子来介绍它的用法。借使大家想要给名为“托德”的用户们发送请求,他们住在圣路易斯,有着“Grand
Poobah”之称。用字符串查询参数达成的呼吁U奥德赛I如下:

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

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

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

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

  除了一句话来表达式和通配符之外,若要实行更扑朔迷离的询问,你不可能不要引入运算符。在那种景况下,运算符自己也是属性值的一局部,能够棉被和衣服务端解析,而不是成为属性名的一片段。当须求复杂的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

  再度强调一下,查询参数名/值对中的属性名要和服务端重返的习性名相匹配。别的,由于排序操作相比较复杂,咱们只对亟待的财富提供排序功能。假如须求的话也能够在客户端对小的财富聚合进行排列。

 

排序

  排序决定了从服务端再次回到的笔录的次第。也正是对响应中的多条记下进行排序。

  同样,大家那边只考虑部分比较不难的事态。推荐使用排序字符串查询参数,它含有了一组用分隔符分隔的属性名。具体做法是,暗许对各种属性名按升序排列,倘使属性名有前缀”-“,则按降序排列。用竖线(”|”)分隔每一种属性名,那和眼下过滤效果中的参数名/值对的做法一样。

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

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

  再度强调一下,查询参数名/值对中的属性名要和服务端重返的属性名相匹配。其余,由于排序操作相比较复杂,大家只对急需的能源提供排序功用。假诺要求的话也足以在客户端对小的能源集合实行排列。

 

劳务版本管理

   坦率地讲,一说到版本就会令人认为很不便,很劳碌,不太简单,甚至会令人觉得难熬——因为那会大增API的复杂度,并同时大概会对客户端产生部分震慑。因而,在API的统筹中要尽量幸免五个例外的本子。

  不协理版本,不将版本控制作为不佳的API设计的依靠。假诺您在APIs的安插中引入版本,那迟早都会让你抓狂。由于重返的数码经过JSON来展现,客户端会由于不一样的版本而接受到差异的品质。那样就会设有有的题目,如从内容本身和表明规则方面改变了二个已存在的习性的意思。

  当然,大家不能够防止API也许在一些时候需求变更重返数据的格式和内容,而那也将造成消费端的局部变迁,大家应该制止实行部分关键的调动。将API举行版本化管理是制止那种重庆大学转变的一种有效措施。

劳务版本管理

   坦率地讲,一说到版本就会令人以为很不便,很麻烦,不太简单,甚至会令人觉着难受——因为那会大增API的复杂度,并同时恐怕会对客户端发生局地震慑。因而,在API的布署中要尽量制止三个例外的版本。

  不协助版本,不将版本控制作为不佳的API设计的信赖。假若你在APIs的规划中引入版本,那迟早都会让您抓狂。由于重回的多少通过JSON来呈现,客户端会由于不相同的本子而接受到差别的习性。那样就会存在一些题材,如从内容小编和认证规则方面改变了叁个已存在的属性的含义。

  当然,大家无能为力制止API也许在好何时候必要转移再次回到数据的格式和情节,而那也将导致消费端的部分变型,大家理应幸免实香港行政局地第①的调整。将API进行版本化管理是防止那种根本变更的一种有效格局。

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

  未来,版本管理通过U奥迪Q7I自己的本子号来完成,客户端在恳求的U本田CR-VI中标明要博取的财富的版本号。事实上,许多大集团如Instagram、Yammer、推特、谷歌等平日在他们的U途乐I里使用版本号。甚至像WSO2那样的API管理工科具也会在它的U奥迪Q7Ls中供给版本号。

  面向REST原则,版本管理技术神速发展。因为它不分包HTTP规范中置放的header,也不帮助仅当3个新的能源或概念被引入时才应该添加新UXC90I的见识——即版本不是表现格局的更动。另3个不予的理由是能源U库罗德I是不会随时间改变的,能源正是财富。

  U陆风X8I应该能大致地辨别能源——而不是它的“形状”(状态)。另3个就是必须钦命响应的格式(表征)。还有一部分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”}

  将来,咱们对同样财富请求版本2的数量:

  #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被用来代表所梦想的响应格式(以及示例中的版本号),注意上述五个一律的U汉兰达I是怎么着成功在不相同的版本中分辨财富的。或许,倘若客户端须求一个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”}

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

  今后,版本管理通过U帕杰罗I本人的版本号来形成,客户端在乞求的UKoleosI中标明要博取的财富的版本号。事实上,许多大商店如推特、Yammer、Instagram、谷歌(Google)等平常在她们的U揽胜极光I里使用版本号。甚至像WSO2那样的API管理工科具也会在它的U纳瓦拉Ls中需要版本号。

  面向REST原则,版本管理技术连忙发展。因为它不包罗HTTP规范中置放的header,也不帮忙仅当1个新的财富或概念被引入时才应该添加新UPAJEROI的见识——即版本不是表现情势的变更。另2个不予的理由是能源U哈弗I是不会随时间改变的,财富正是能源。

  UPRADOI应该能大约地分辨财富——而不是它的“形状”(状态)。另四个正是必须钦命响应的格式(表征)。还有一些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”}

  以后,大家对同一财富请求版本2的数目:

  #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被用来代表所企盼的响应格式(以及示例中的版本号),注意上述四个相同的UHighlanderI是哪些做到在区别的本子中分辨财富的。大概,假设客户端须求2个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在发送数据给服务器时的用途,这里给出叁个用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”}

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

  并不必要在每3个请求中都内定版本号。由于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格式请求八个含有多版本财富的服务器,来创制贰个新用户(预期会回去版本1):

  #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个请求中都钦赐版本号。由于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格式请求1个饱含多版本能源的服务器,来创建二个新用户(预期会回到版本1):

  #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”}

呼吁不辅助的本子

  当呼吁3个不帮忙的本子号时(包蕴在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”]

伸手不帮忙的版本

  当呼吁三个不帮助的本子号时(包涵在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”]

怎么时候理应制造贰个新本子?

  API开发中的很多地点都会打破约定,并最后对客户端发生部分不良影响。如若您不明确API的改动会拉动什么的结局,有限支撑起见最棒考虑采用版本控制。当您在考虑提供一个新本子是还是不是合宜时,或许考虑对现有的回到表征进行改动是不是必然能满足急需并被客户端所收受时,有如此几个要素要考虑。

永利网上娱乐,怎么着时候理应创制八个新本子?

  API开发中的很多地点都会打破约定,并最后对客户端产生部分不良影响。假若你不明确API的改动会带来怎样的后果,保障起见最佳考虑使用版本控制。当你在设想提供贰个新本子是或不是适当时,可能考虑对现有的回来表征进行修改是还是不是必然能满意急需并被客户端所接受时,有那般多少个因素要考虑。

破坏性的改动

  • 更改属性名(例如将”name”改成”firstName”)
  • 剔除属性
  • 转移属性的数据类型(例如将numeric变为string,
    boolean变为bit/numeric,string 变为 datetime等等)
  • 变动验证规则
  • 在Atom样式的链接中,修改”rel”的值
  • 在存活的工作流中引入需求能源
  • 改变财富的定义/意图;概念/意图或能源意况的含义不一致于它原有的含义。例如:
    • 二个content
      type是text/html的能源,在此之前表示的是有所补助的媒体类型的2个”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的能源,此前表示的是富有协助的传播媒介类型的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能源的链接被移除。

  就算上边列出的并不周密,但它交给了一部分会对客户端发生破坏性影响的更动类型,那时急需考虑提供八个新能源或新本子。

非破坏性的修改

  • 在重临的JSON中添加新属性
  • 丰硕指向任何财富的”link”
  • 添加content-type接济的新格式
  • 添加content-language帮助的新格式
  • 由于API的创制者和消费者都要处理差别的casing,因而casing的浮动非亲非故主要

非破坏性的改动

  • 在回来的JSON中添加新属性
  • 添加指向任何财富的”link”
  • 添加content-type支持的新格式
  • 添加content-language帮忙的新格式
  • 鉴于API的创始人和买主都要拍卖不一样的casing,因而casing的浮动毫不相关重要

版本控制应在怎么级别出现?

  提议对单个的能源开展版本控制。对API的一部分改成,如修改工作流,或然要跨多少个财富的版本控制,以此来严防对客户端发生破坏性的熏陶。

版本控制应在怎样级别出现?

  提出对单个的资源开始展览版本控制。对API的一对改变,如修改工作流,或然要跨几个财富的版本控制,以此来预防对客户端发生破坏性的熏陶。

利用Content-Location来加强响应

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

接纳Content-Location来抓牢响应

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

带有Content-Type的链接

  Atom风格的链接协理”type”属性。提供丰盛的信息以便客户端可以对特定的版本和剧情类型举行调用。

带有Content-Type的链接

  Atom风格的链接援助”type”属性。提供丰盛的消息以便客户端能够对特定的版本和内容类型实行调用。

找出协助的本子

找出补助的本子

自身应该而且帮助多少个本子?

  维护多少个不等的本子会让劳作变得繁琐、复杂、不难失误,而且代价高,对于其余给定的财富,你应当帮忙不超越贰个版本。

本人应该而且援救多少个本子?

  维护八个例外的版本会让工作变得繁琐、复杂、简单出错,而且代价高,对于此外给定的财富,你应当协理不超越2个本子。

弃用

  Deprecated(弃用)的目标是用来表明财富对API依旧可用,但在现在会不存在并变得不可用。小心:弃用的时间长度将由弃用政策决定——这里并从未提交定义。

弃用

  Deprecated(弃用)的目标是用来评释能源对API仍旧可用,但在现在会不设有并变得不可用。小心:弃用的时长将由弃用政策决定——那里并从未交给定义。

自己怎样告知客户端被弃用的财富?

  许多客户端以后访问的能源只怕在新本子引入后会被甩掉掉,由此,他们需求有一种艺术来发现和监察他们的应用程序对弃用能源的接纳。当呼吁一个弃用财富时,API应该符合规律响应,并包罗一个布尔类型的自定义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”}

 

本身怎么着告知客户端被弃用的财富?

  许多客户端现在造访的财富恐怕在新本子引入后会被放任掉,因而,他们须要有一种方法来发现和监察他们的应用程序对弃用财富的运用。当呼吁一个弃用能源时,API应该不奇怪响应,并包罗贰个布尔类型的自定义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”}

 

日期/时间拍卖

  若是没有稳当地、一致地处理好日期和岁月来说,那将成为二个大麻烦。我们经常会遭遇时区的难点,而且由于日期在JSON中是以字符串的格式存在的,如若未钦点统一的格式,那么解析日期也会是三个难题。

  在接口内部,服务端应该以UTC或GMT时间来储存、处理和缓存时间戳。那将实用消除日期和时间的难题。

日期/时间拍卖

  假如没有安妥地、一致地处理好日期和岁月的话,那将改成多个大麻烦。咱们平时会遇上时区的难题,而且由于日期在JSON中是以字符串的格式存在的,倘使未内定统一的格式,那么解析日期也会是1个标题。

  在接口内部,服务端应该以UTC或创新霉素T时间来储存、处理和缓存时间戳。那将有效解决日期和岁月的问题。

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

  有3个总结的措施能够化解这个标题——在字符串中始终用同样的格式,包涵时间片(带有时区消息)。ISO8601时间格式是多个不易的消除方案,它使用了一心增强的时间格式,包含时辰、分钟、秒以及秒的小数部分(例如yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)。提议在REST服务的body内容中(请求和响应均包含)使用ISO8601代表全体的日期格式。

  顺便提一下,对于那多少个基于JAVA的劳动来说,DateAdapterJ库使用DateAdapter,Iso8601TimepointAdapter和HttpHeaderTimestampAdapter类能够卓殊不难地剖析和格式化ISO860114日期和时间,以及HTTP
1.1
header(凯雷德FC1123)格式。能够从https://github.com/tfredrich/DateAdapterJ下载。

  对于那些成立基于浏览器的用户界面来说,ECMAScript5标准一开头就包罗了JavaScript解析和创造ISO860七日期的始末,所以它应该成为我们所说的主流浏览器所服从的法子。当然,如果您要支持那1个不能够自动解析日期的旧版浏览器,可以使用JavaStript库或正则表明式。那里有多少个能够分析和创办ISO8601时间的JavaStript库:

  http://momentjs.com/

  http://www.datejs.com/

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

  有三个归纳的点子能够缓解这几个题材——在字符串中始终用同样的格式,包涵时间片(带有时区消息)。ISO8601时间格式是二个科学的缓解方案,它使用了完全增强的年月格式,包罗小时、分钟、秒以及秒的小数部分(例如yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)。指出在REST服务的body内容中(请求和响应均包蕴)使用ISO8601代表全数的日期格式。

  顺便提一下,对于那些基于JAVA的服务来说,DateAdapterJ库使用DateAdapter,Iso8601TimepointAdapter和HttpHeaderTimestampAdapter类能够相当不难地解析和格式化ISO860二二十日期和时间,以及HTTP
1.1
header(PRADOFC1123)格式。能够从https://github.com/tfredrich/DateAdapterJ下载。

  对于那几个创设基于浏览器的用户界面来说,ECMAScript5正经一起头就带有了JavaScript解析和创制ISO860二16日期的内容,所以它应当成为我们所说的主流浏览器所遵循的艺术。当然,若是您要帮助那几个不能够自动解析日期的旧版浏览器,能够应用JavaStript库或正则说明式。那里有多少个能够分析和创办ISO8601时间的JavaStript库:

  http://momentjs.com/

  http://www.datejs.com/

HTTP Headers中的日期/时间类别化

  然则上述提议仅适用于HTTP请求或响应内容中的JSON和XML内容,HTTP规范针对HTTP
headers使用另一种不相同的格式。在被昂科威FC1123更替的PRADOFC82第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使用另一种分化的格式。在被LX570FC1123更替的索罗德FC82第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. 客户端发起八个请求,将authentication的token(身份验证令牌)包蕴在X-Authentication
    header中,或者将token叠加在伏乞的查询串参数中。
  2. 服务器对authorization
    token(授权令牌)进行自作者批评,并拓展认证(有效且未过期),并基于令牌内容分析恐怕加载认证大旨。
  3. 服务器调用授权服务,提供注脚中央、被呼吁能源和必备的操作许可。
  4. 一旦授权通过了,服务器将会继续健康运营。

  上边第二步的付出只怕会相比较大,但是只要若是存在贰个可缓存的权位控制列表(ACL),那么在发生远程请求前,能够在地面创立一个授权客户端来缓存最新的ACLs。

爱护服务的鄂州

  Authentication(身份验证)指的是承认给定的请求是从服务已知的某人(或某些系统)发出的,且请求者是他自个儿所注解的越发人。Authentication是为着表达请求者的真人真事身份,而authorization(授权)是为了求证请求者有权力去履行被呼吁的操作。

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

  1. 客户端发起一个请求,将authentication的token(身份验证令牌)包罗在X-Authentication
    header中,或者将token叠加在央求的查询串参数中。
  2. 服务器对authorization
    token(授权令牌)实行检讨,并开始展览表明(有效且未过期),并基于令牌内容分析恐怕加载认证宗旨。
  3. 服务器调用授权服务,提供验证宗旨、被呼吁能源和须要的操作许可。
  4. 倘使授权通过了,服务器将会延续健康运转。

  上边第一步的支出大概会相比大,可是倘诺借使存在三个可缓存的权位控制列表(ACL),那么在发生远程请求前,能够在地点创制一个授权客户端来缓存最新的ACLs。

身份验证

  近年来最棒的做法是运用OAuth身份验证。强烈推荐OAuth2,可是它照旧处于草案意况。也许选拔OAuth1,它完全能够胜任。在好几境况下也足以选拔3-Legged
OAuth。更多关于OAuth的正式可以查看那里http://oauth.net/documentation/spec/

  OpenID是1个增公投择。不过建议将OpenID作为3个外加的身份验证选项,以OAuth为主。越来越多关于OpenID的科班能够查看这里http://openid.net/developers/specs/

身份验证

  如今最棒的做法是选拔OAuth身份验证。强烈推荐OAuth2,但是它照旧居于草案情状。大概选拔OAuth1,它完全能够胜任。在好几意况下也能够挑选3-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。

授权

  对劳务的授权和对别的应用程序的授权一样,没有此外分歧。它依据那样二个标题:“主体是或不是对给定的资源有请求的许可?”那里给出了归纳的三项数据(主体,财富和许可),由此很简单构造一个匡助这种概念的授权服务。在那之中焦点是被予以能源访问许可的人或系统。使用那几个相似概念,就足以为每2个大旨创设3个缓存访问控制列表(ALC)。

授权

  对劳动的授权和对别的应用程序的授权一样,没有别的差距。它依照那样1个难题:“主体是不是对给定的资源有请求的许可?”那里给出了大致的三项数据(主体,能源和承认),由此很简单构造3个支撑那种概念的授权服务。在那之中核心是被赋予财富访问许可的人或种类。使用那个相似概念,就能够为每一个大旨构建1个缓存访问控制列表(ALC)。

应用程序安全

  对RESTful服务来说,开发一个平安的web应用适用同样的规则。

  • 在服务器上印证全体输入。接受“已知”的科学的输入并驳回错误的输入。
  • 防止SQL和NoSQL注入。
  • 动用library如微软的Anti-XSS或OWASP的Anti萨姆my来对输出的数据开始展览编码。
  • 将新闻的长短限制在规定的字段长度内。
  • 劳务应该只显示一般的错误新闻。
  • 考虑工作逻辑攻击。例如,攻击者能够跳过多步骤的订座流程来预定产品而无需输入信用卡音信呢?
  • 对可疑的位移记录日志。

  RESTful安全需求小心的地点:

  • 表明数据的JSON和XML格式。
  • HTTP动词应该被界定在同意的艺术中。例如,GET请求不可能去除贰个实体。GET用来读取实体而DELETE用来删除实体。
  • 留意race
    conditions(竞争规则——由于四个恐怕两个过程竞争使用不可能被同时做客的能源,使得这一个进度有可能因为时间上有助于的顺序原因此产出难题)。

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

  • 监视API的运用状态,并询问什么活动是常规的,哪些是非平常的。
  • 限定API的应用,使恶意用户不可能停掉叁个API服务(DOS攻击),并且有能力阻止恶意的IP地址。
  • 将API密钥存款和储蓄在加密的平安密钥库中。

 

应用程序安全

  对RESTful服务以来,开发一个安全的web应用适用同样的口径。

  • 在服务器上证实全数输入。接受“已知”的正确性的输入并驳回错误的输入。
  • 防止SQL和NoSQL注入。
  • 应用library如微软的Anti-XSS或OWASP的Anti萨姆my来对输出的数码进行编码。
  • 将音讯的长短限制在明确的字段长度内。
  • 服务应该只展现一般的错误音信。
  • 考虑工作逻辑攻击。例如,攻击者能够跳过多步骤的订座流程来预约产品而无需输入信用卡音信呢?
  • 对疑惑的活动记录日志。

  RESTful安全须求小心的地点:

  • 表明数据的JSON和XML格式。
  • HTTP动词应该被限制在允许的办法中。例如,GET请求无法去除一个实体。GET用来读取实体而DELETE用来删除实体。
  • 专注race
    conditions(竞争规则——由于四个可能多个经过竞争使用不可能被同时做客的能源,使得这个进程有大概因为日子上拉动的顺序原由此产出难题)。

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

  • 蹲点API的应用状态,并询问怎么着活动是例行的,哪些是非平常的。
  • 限定API的行使,使恶意用户不能够停掉1个API服务(DOS攻击),并且有力量阻止恶意的IP地址。
  • 将API密钥存款和储蓄在加密的安全密钥库中。

 

缓存和可伸缩性

  通过在系统层级消除通过远程调用来赢得请求的数额,缓存提升了系统的可增添性。服务通过在响应中安装headers来拉长缓存的力量。遗憾的是,HTTP
1.0中与缓存相关的headers与HTTP
1.1例外,由此服务器要同时协理三种版本。下表给出了GET请求要帮衬缓存所必须的最少headers集合,并交由了方便的叙说。

HTTP Header

描述

示例

Date

响应重返的日子和岁月(RubiconFC1123格式)。

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

Cache-Control

响应可被缓存的最大秒数(最大age值)。假若响应不帮衬缓存,值为no-cache。

Cache-Control: 360

Cache-Control: no-cache

Expires

一经给出了最大age值,该时间戳(LacrosseFC1123格式)表示的是响应过期的时日,也正是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

财富本身最后被改动的时间戳(奥德赛FC1123格式)。

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

  为了简化,那里举贰个响应中的headers集合的事例。那是二个总结的对能源开始展览GET请求的响应,缓存时间长度为一天(24钟头):

  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

缓存和可伸缩性

  通过在系统层级消除通过远程调用来获得请求的数码,缓存进步了系统的可扩大性。服务通过在响应中安装headers来狠抓缓存的力量。遗憾的是,HTTP
1.0中与缓存相关的headers与HTTP
1.1见仁见智,因而服务器要同时扶助两种版本。下表给出了GET请求要协助缓存所必须的最少headers集合,并交由了合适的叙说。

HTTP Header

描述

示例

Date

一呼百应重回的日子和岁月(LANDFC1123格式)。

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

资源本人最终被涂改的时光戳(GL450FC1123格式)。

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

  为了简化,那里举2个响应中的headers集合的事例。这是2个简便的对财富开始展览GET请求的响应,缓存时间长度为一天(24钟头):

  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与平等能源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壹 、403的范围,当呼吁的财富找不到时,出于安全因素考虑,服务器都得以动用该错误码来掩饰。

  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)
—— 无论能源存不设有,无论是否有40一 、403的限制,当呼吁的能源找不到时,出于安全因素考虑,服务器都可以运用该错误码来掩盖。

  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

相关文章