依照财富,基于财富

正文首要读者

正文主要读者

引言

引言

REST是什么

REST是什么

  集合接口

  合并接口

    根据能源

    听别人说财富

    通过特征来操作能源

    透过特征来操作财富

    自描述的音信

    自描述的音信

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

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

  无状态

  无状态

  可缓存

  可缓存

  C-S架构

  C-S架构

  支行系统

  分段系统

  按需编码(可选)

  按需编码(可选)

REST飞速提醒

REST火速提醒

  采纳HTTP动词表示1些意义

  行使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

查询,过滤和分页

查询,过滤和分页

  结果限制

  结果限制

    用范围标记进行限定

    用范围标记进行限制

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

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

    基于范围的响应

    据他们说范围的响应

  分页

  分页

  结果的过滤和排序

  结果的过滤和排序

    过滤

    过滤

    排序

    排序

劳动版本管理

劳务版本管理

  因而内容协商协理版本管理

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

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

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

  恳请不帮助的本子

  伸手不扶助的本子

  怎么时候理应成立1个新本子?

  什么日期理应创设三个新本子?

    破坏性的改动

    破坏性的改动

    非破坏性的修改

    非破坏性的修改

  版本控制应在如何级别出现?

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

  选取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服务感兴趣的开发职员,该服务为跨多少个服务的机件提供了较高的可相信性和一致性。依据本文的指引,可高效、广泛、公开地为内外部客户使用。

  本文中的引导规范1致适用于工程师们,他们期望利用那个依照最棒实践标准开发的劳动。固然他们进一步关怀缓存、代理规则、监听及康宁等荣辱与共地方,可是该文书档案能作为一份包涵全部品类服务的总指南。

  其余,通过从这一个指引原则,管理人士领会到创立公共的、提供高稳定的劳动所需开销的拼命,他们也可从中受益。

 

引言

  至今已有雅量关于RESTful
Web服务至上实践的相干材质(详见本文最终的有关文献部分)。由于撰文的日子不一,许多素材中的内容是龃龉的。别的,想要通过查阅文献来询问那种劳动的前进是不太可取的。为了精通RESTful这一定义,至少供给查阅三到伍本有关文献,而本文将能够帮您加速那一经过——舍弃多余的商量,最大化地提炼出REST的顶级实践和行业内部。

  与其说REST是一套标准,REST更像是一种规格的联谊。除了五个十分重要的规范外就从不别的的正儿捌经了。实际上,纵然有所谓的“最棒实践”和标准,但那一个事物都和宗教斗争壹样,在时时刻刻地演化。

  本文围绕REST的普遍难点建议了意见和仿食谱式的座谈,并经过介绍部分简练的背景知识对创立真实情形下的预生产条件中相同的REST服务提供文化。本文收集了来自其余渠道的音讯,经历过二次次的挫败后不断创新。

  但对此REST情势是不是必然比SOAP好用仍有较大争议(反之亦然),可能在壹些情状下仍急需创设SOAP服务。本文在谈到SOAP时并未有花较大篇幅来切磋它的周旋优点。相反由于技术和行业在不断提升,大家将一连持之以恒大家的倘使–REST是即时规划web服务的极品艺术。

  第三片段概述REST的意思、设计准则和它的非正规之处。第1某个点数了有个别小贴士来回想REST的劳务意见。之后的有的则会越来越深刻地为web服务创制职员提供一些细节的支撑和座谈,来促成三个可见公开始展览示在生育条件中的高品质REST服务。

 

引言

  于今已有大气有关RESTful
Web服务至上实践的连带资料(详见本文最终的连锁文献部分)。由于撰文的时间不1,许多材质中的内容是争辩的。其它,想要通过翻看文献来打探那种服务的向上是不太可取的。为了打探RESTful这一定义,至少要求查阅3到5本有关文献,而本文将能够帮你加速那一进度——抛弃多余的探究,最大化地提炼出REST的特级实践和规范。

  与其说REST是一套标准,REST更像是壹种标准的汇集。除了七个主要的准绳外就从未有过别的的标准了。实际上,纵然有所谓的“最好实践”和正规,但这一个事物都和宗派斗争1样,在不停地演化。

  本文围绕REST的宽广难题提议了看法和仿食谱式的座谈,并通过介绍部分简约的背景知识对创立真实情况下的预生产环境中相同的REST服务提供文化。本文收集了来自其余渠道的信息,经历过二遍次的败诉后不断革新。

  但对于REST情势是或不是肯定比SOAP好用仍有较大争议(反之亦然),只怕在少数情状下仍急需创制SOAP服务。本文在谈起SOAP时并未有花较大篇幅来谈谈它的相对优点。相反由于技术和行业在不断进步,我们将继续滴水穿石大家的借使–REST是马上安顿web服务的一流办法。

  第三局地概述REST的意思、设计准则和它的卓越之处。第贰片段点数了1些小贴士来回忆REST的劳动理念。之后的有个别则会越来越深远地为web服务成立人员提供1些细节的支撑和座谈,来贯彻一个能够公开始展览示在生育环境中的高质量REST服务。

 

REST是什么?

  REST架构情势讲述了四种设计准则。这几个用于架构的设计准则,最早是由RoyFielding在他的学士随想中提议并定义了RESTful风格。(详见http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

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

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

  以下是那些规划准则的详尽谈论:

REST是什么?

  REST架构方式讲述了各样设计准则。那些用于架构的宏图准则,最早是由罗伊Fielding在她的博士故事集中提议并定义了RESTful风格。(详见http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

  多少个规划准则分别是:

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

  以下是这几个规划准则的详细谈论:

统1接口

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

集合接口

  统一接口准则定义了客户端和服务端之间的接口,简化和分手了框架结构,那样一来各类部分都可单独演变。以下是接口统一的几个原则:

  基于能源

  分裂能源供给用U路虎极光I来唯一标识。再次来到给客户端的风味和财富本人在概念上有所不相同,例如服务端不会间接传送贰个数据库能源,但是,1些HTML、XML或JSON数据可见显得部分数据库记录,如用印度语印尼语来揭橥依旧用UTF-8编码则要基于请求和服务器达成的细节来支配。

  基于财富

  差异能源必要用UWranglerI来唯一标识。再次来到给客户端的风味和财富本人在概念上有所分裂,例如服务端不会直接传送3个数据库财富,然则,壹些HTML、XML或JSON数据可见显示部分数据库记录,如用匈牙利语来表明照旧用UTF-八编码则要依照请求和服务器落成的底细来控制。

  通过特色来操作财富

  当客户端收到包罗元数据的财富的个性时,在有权力的场合下,客户端已控制的够用的音信,能够对服务端的财富拓展删改。

  通过特色来操作财富

  当客户端收到包括元数据的能源的特色时,在有权力的情事下,客户端已控制的够用的新闻,能够对服务端的能源开展删改。

  自描述的新闻

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

  自描述的音讯

  每条音信都富含丰盛的数据用于确认音信该怎样处理。例如要由互连网媒体类型(已知的如MIME类型)来确认需调用哪个解析器。响应同样也申明了它们的缓存能力。

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

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

  除了上述剧情外,HATEOS也表示,须要的时候链接也可被含有在再次来到的body(或底部)中,以提供UXC90I来查找对象自小编或关系对象。下文将对此实行更详细的阐发。

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

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

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

  除了上述内容外,HATEOS也象征,须要的时候链接也可被含有在回来的body(或头部)中,以提供UCR-VI来探寻对象自作者或提到对象。下文将对此实行更详尽的论述。

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

无状态

  正如REST是REpresentational State
Transfer的缩写,无状态很要紧。本质上,那标志了拍卖请求所需的情事已经包涵在乞请小编里,也有望是U翼虎I的一片段、查询串参数、body或尾部。UPAJEROI能够唯一标识每一种财富,body中也隐含了财富的转态(或转态变更处境)。之后,服务器将举办拍卖,将相关的情景或能源通过头部、状态和响应body传递给客户端。

  从事大家这一行当的超过二分之一人都习惯使用容器来编制程序,容器中有2个“会话”的概念,用于在四个HTTP请求下保持状态。在REST中,假若要在七个请求下维持用户景况,客户端必须回顾客户端的装有音信来形成请求,须要时再也发送请求。自从服务端不须要保持、更新或传递会话状态后,无状态性获得了越来越大的延展。此外,负载均衡器无需担心和无状态系统里面包车型客车对话。

  所以状态和能源间有啥样异样?服务器对于状态,大概说是应用状态,所关切的点是在脚下对话或请求中要成功请求所需的数额。而能源,恐怕说是能源气象,则是概念了财富特色的多少,例如存款和储蓄在数据库中的数据。总而言之,应用状态是是随着客户端和央浼的变更而更改的数据。相反,能源情状对于发出请求的客户端的话是不变的。

  在互联网利用的某壹一确定工作岗位位上安顿贰个回到按钮,是因为它愿意您能按一定的相继来操作吗?其实是因为它违反了无状态的基准。有广大不听从无状态原则的案例,例如三-Legged
OAuth,API调用速度限制等。但依旧要尽量保险服务器中不必要在七个请求下维持利用状态。

无状态

  正如REST是REpresentational State
Transfer的缩写,无状态很重大。本质上,那标志了拍卖请求所需的情景已经包罗在伸手笔者里,也有十分的大可能是U酷路泽I的1部分、查询串参数、body或底部。U奥迪Q五I能够唯一标识每一个财富,body中也饱含了能源的转态(或转态变更情状)。之后,服务器将开展处理,将有关的图景或财富通过尾部、状态和响应body传递给客户端。

  从事我们那1行当的绝超过61%人都习惯使用容器来编程,容器中有三个“会话”的定义,用于在多少个HTTP请求下维持状态。在REST中,如若要在多少个请求下保持用户意况,客户端必须归纳客户端的兼具音信来实现请求,供给时再次发送请求。自从服务端不必要保险、更新或传递会话状态后,无状态性获得了更加大的延展。其余,负载均衡器无需担心和无状态系统里头的对话。

  所以状态和财富间有怎样差异?服务器对于状态,或然说是应用状态,所关注的点是在当前对话或请求中要到位请求所需的数目。而能源,恐怕说是财富情状,则是概念了能源特点的数额,例如存款和储蓄在数据库中的数据。一言以蔽之,应用状态是是随着客户端和呼吁的改观而变更的多寡。相反,财富意况对于发出请求的客户端的话是不变的。

  在网络选取的某1一定岗位上摆放多个重临按钮,是因为它仰望你能按自然的次第来操作吗?其实是因为它违反了无状态的口径。有成都百货上千不遵从无状态原则的案例,例如三-Legged
OAuth,API调用速度限制等。但照旧要硬着头皮保险服务器中不供给在多少个请求下维持利用状态。

可缓存

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

可缓存

  在万维网上,客户端能够缓存页面包车型地铁响应内容。因而响应都应隐式或显式的概念为可缓存的,若不足缓存则要防止客户端在频仍请求后用旧数据或脏数据来响应。管理稳当的缓存会部分地或完全地除了客户端和服务端之间的相互,进一步立异质量和延展性。

C-S架构

  统壹接口使得客户端和服务端相互分开。关切分离意味什么?打个假设,客户端不要求仓库储存数据,数据都留在服务端内部,那样使得客户端代码的可移植性得到了升级;而服务端不必要思索用户接口和用户意况,那样一来服务端将更为简便易行易拓展。只要接口不改动,服务端和客户端能够独自地开始展览研究开发和替换。

C-S架构

  统1接口使得客户端和服务端互相分开。关怀分离意味什么?打个假使,客户端不要求仓库储存数据,数据都留在服务端内部,那样使得客户端代码的可移植性得到了晋升;而服务端不要求思念用户接口和用户情状,那样1来服务端将进而简约易拓展。只要接口不转移,服务端和客户端能够独立地拓展研究开发和替换。

分层系统

  客户端平常无法申明自身是直接只怕直接与端服务器实行连接。中介服务器能够因而启用负载均衡或提供共享缓存来提高系统的延展性。分层时同样要思考安全策略。

分层系统

  客户端常常无法申明自个儿是一直只怕间接与端服务器举办连接。中介服务器能够通过启用负载均衡或提供共享缓存来进步系统的延展性。分层时同样要考虑安全策略。

按需编码(可选)

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

  服从上述原则,与REST架构风格保持1致,能让各类分布式超媒连串统具备梦想的自然属性,比如高质量,延展性,简洁,可变性,可视化,可移植性和可靠性。

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

 

按需编码(可选)

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

  服从上述条件,与REST架构风格保持壹致,能让各个分布式超媒系列统具备梦想的自然属性,比如高品质,延展性,简洁,可变性,可视化,可移植性和可信赖性。

  提示:REST架构中的陈设准则中,唯有按需编码为可选项。就算有些服务违反了别的随意一项准则,严苛意思上无法称之为RESTful风格。

 

REST快捷提示

  (依据上面提到的五个条件)不管在技术上是否RESTful的,那里有壹部分类似REST概念的提议。遵从它们,能够兑现更加好、更有效的劳务:

REST神速提示

  (依照上面提到的三个尺码)不管在技术上是或不是RESTful的,那里有1部分看似REST概念的建议。遵守它们,能够达成越来越好、更有效的劳务:

选用HTTP动词表示一些含义

  任何API的使用者能够发送GET、POST、PUT和DELETE请求,它们极大程度鲜明了所给请求的目标。同时,GET请求不能够更改任何秘密的能源数量。测量和跟踪仍大概产生,但只会更新数据而不会更新由U宝马X5I标识的能源数量。

运用HTTP动词表示1些含义

  任何API的使用者能够发送GET、POST、PUT和DELETE请求,它们非常大程度彰着了所给请求的目标。同时,GET请求不能够更改任何秘密的财富数量。衡量和跟踪仍也许发生,但只会更新数据而不会更新由U智跑I标识的能源数量。

合理的能源名

  合理的财富名称可能路径(如/posts/二3而不是/api?type=posts&id=贰三)能够更通晓三个伸手的目标。使用U奥迪Q3L查询串来过滤数据是很好的主意,但不该用于固定财富名称。

  适当的能源名称叫服务端请求提供上下文,扩张服务端API的可精通性。通过U安德拉I名称分层地翻看能源,可以给使用者提供一个和谐的、简单精晓的财富层次,以在她们的应用程序上利用。财富名称应当是名词,幸免为动词。使用HTTP方法来钦点请求的动作部分,能让工作越来越的分明。

创建的能源名

  合理的能源名称只怕路径(如/posts/二三而不是/api?type=posts&id=2三)能够更领悟一个请求的指标。使用U本田CR-VL查询串来过滤数据是很好的主意,但不应有用于固定能源名称。

  适当的财富名叫服务端请求提供上下文,扩展服务端API的可精通性。通过U昂CoraI名称分层地查看能源,能够给使用者提供1个祥和的、简单精通的财富层次,以在她们的应用程序上运用。能源名称应当是名词,制止为动词。使用HTTP方法来钦赐请求的动作部分,能让工作越来越的明领会白。

XML和JSON

  提出私下认可帮助json,并且,除非费用很惊人,不然就同时扶助json和xml。在地道图景下,让使用者仅通过改变扩充名.xml和.json来切换类型。别的,对于支撑ajax风格的用户界面,3个被卷入的响应是卓殊有赞助的。提供一个棉被服装进的响应,在暗中同意的依旧有单独增加名的状态下,例如:.wjson和.wxml,表明客户端请求二个被打包的json或xml响应(请参见下边的包裹响应)。

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

  关于REST服务中xml的运用,xml的正儿八经和预定除了接纳语法正确的竹签和文本外没有任何的机能。尤其地,命名空间不是也不应当是被运用在REST服务端的上下文中。xml的回到更接近于json——简单、简单阅读,未有情势和命名空间的细节表现——仅仅是数据和链接。尽管它比那更扑朔迷离的话,参看本节的第2段——使用xml的基金是惊心动魄的。鉴于大家的经历,很少有人使用xml作为响应。在它被全然淘汰此前,那是终极三个可被一定的地方。

XML和JSON

  提出暗中认可支持json,并且,除非费用很惊人,不然就同时援救json和xml。在理想图景下,让使用者仅经过改动扩展名.xml和.json来切换类型。其它,对于支撑ajax风格的用户界面,3个被包裹的响应是老大有援助的。提供三个被打包的响应,在默许的要么有单独扩张名的动静下,例如:.wjson和.wxml,表明客户端请求1个被装进的json或xml响应(请参见上面的包装响应)。

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

  关于REST服务中xml的采纳,xml的业内和预定除了选用语法正确的标签和文本外未有其余的意义。尤其地,命名空间不是也不应该是被利用在REST服务端的左右文中。xml的回到更类似于json——容易、简单阅读,没有格局和命名空间的细节表现——仅仅是数量和链接。要是它比那更扑朔迷离的话,参看本节的首先段——使用xml的老本是震惊的。鉴于我们的经验,很少有人使用xml作为响应。在它被统统淘汰在此以前,那是最终1个可被一定的地点。

创办适当粒度的财富

  一开端,系统中模拟底层应用程序域或数据库架构的API更便于被创立。最后,你会期待将这一个服务都构成到一块儿——利用多项底层能源裁减通讯量。在创建独立的能源之后再次创下制更加大粒度的能源,比从越来越大的合集中创造较大粒度的财富越来越不难壹些。从一些小的简单定义的财富开始,创设CRUD(增加和删除查改)效能,能够使资源的开创变得更易于。随后,你能够创建这么些依照用例和收缩通信量的能源。

创办适当粒度的能源

  1开首,系统中效仿底层应用程序域或数据库架构的API更便于被创立。最后,你会希望将这个劳动都构成到壹块——利用多项底层财富减弱通讯量。在开立独立的能源之后再次创下造更加大粒度的财富,比从越来越大的合集中成立较大粒度的财富越来越简单1些。从1些小的不难定义的财富初始,创立CRUD(增删查改)作用,能够使财富的创办变得更便于。随后,你能够创立那么些依据用例和削减通讯量的财富。

设想连通性

  REST的规律之壹正是连通性——通过超媒体链接完结。当在响应中回到链接时,api变的更享有自描述性,而在尚未它们时服务端照旧可用。至少,接口自己能够为客户端提供什么样寻找数据的参照。其它,在经过POST方法创制财富时,还足以行使头地点包涵3个链接。对于响应中补助分页的聚合,”first”、
“last”、”next”、和”prev”链接至少是不行政管理用的。

 

思考连通性

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

 

定义

定义

幂等性

  不要从字面意思来通晓什么是幂等性,恰恰相反,这与1些职能紊乱的世界非亲非故。下边是根源维基百科的解释:

在总结机科学中,术语幂等用于更周全地描述叁个操作,三回或频仍进行该操作爆发的结果是平等的。依照使用的上下文,那可能有例外的含义。例如,在点子依然子例程调用全数副作用的气象下,意味着在率先调用之后被改动的景观也有限支撑不变。

  从REST服务端的角度来看,由于操作(或服务端调用)是幂等的,客户端能够用重新的调用而发出相同的结果——在编程语言中操作像是3个”setter”(设置)方法。换句话说,正是选拔多少个一样的呼吁与行使单个请求效果等同。注意,当幂等操作在服务器上发生相同的结果(副功用),响应本身只怕是见仁见智的(例如在多少个请求之间,财富的情状大概会转移)。

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

幂等性

  不要从字面意思来明白什么是幂等性,恰恰相反,那与有些功用紊乱的领域非亲非故。下边是来自维基百科的诠释:

在统计机科学中,术语幂等用于更周详地讲述一个操作,二遍或频仍履行该操作发生的结果是壹样的。遵照使用的上下文,那只怕有两样的意思。例如,在艺术或然子例程调用全体副成效的图景下,意味着在首先调用之后被修改的境况也保持不变。

  从REST服务端的角度来看,由于操作(或服务端调用)是幂等的,客户端能够用重新的调用而发生相同的结果——在编制程序语言中操作像是3个”setter”(设置)方法。换句话说,就是行使多少个相同的央求与利用单个请求效果1样。注意,当幂等操作在服务器上发出相同的结果(副功能),响应本人或许是分歧的(例如在多少个请求之间,能源的情形也许会变动)。

  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格式的数据,以及1个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)请求仅用于读取数据而不改变多少。由此,这种应用办法被认为是平安的。也正是说,它们的调用未有数据修改或污染的高风险——调用3次和调用13遍依旧尚未被调用的效益1样。别的,GET(以及HEAD)是幂等的,那意味使用多少个1律的央浼与应用单个的央浼最后都持有一致的结果。

  不要通过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奇骏I中带有的能源ID值在服务器上不存在,则用于成立能源。同时呼吁的body中务必含有要成立的财富的数量。有人认为那会产生歧义,所以唯有真的须求,使用那种办法来创设能源应该被慎用。

  只怕大家也得以在body中提供由客户端定义的财富ID然后使用POST来创立新的财富——借使请求的U奇骏I中不带有要开创的能源ID(参见上边POST的1对)。

  例如:

*  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状态码是201。响应的body是可选的——假设提供的话将会损耗更加多的带宽。在开创财富洋气未须要通过底部的岗位重临链接,因为客户端已经设置了能源ID。请参见下边包车型客车重返值部分。

  PUT不是三个有惊无险的操作,因为它会修改(或创办)服务器上的处境,但它是幂等的。换句话说,若是您利用PUT创立恐怕更新财富,然后重新调用,能源照旧存在并且状态不会发生变化。

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

PUT

  PUT常常被用于立异能源。通过PUT请求三个已知的财富U福睿斯I时,供给在央求的body中包涵对原有财富的翻新数据。

  可是,在能源ID是由客服端而非服务端提供的图景下,PUT同样能够被用来创建财富。换句话说,假诺PUT请求的UPAJEROI中隐含的财富ID值在服务器上不设有,则用于成立财富。同时呼吁的body中务必含有要创设的财富的数额。有人认为那会发生歧义,所以唯有真的必要,使用那种办法来创建财富应该被慎用。

  只怕大家也得以在body中提供由客户端定义的能源ID然后使用POST来创立新的能源——尽管请求的UPRADOI中不带有要开创的能源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状态码是20一。响应的body是可选的——如果提供的话将会损耗更加多的带宽。在开创能源前卫未供给通过尾部的岗位再次来到链接,因为客户端已经设置了财富ID。请参见上边包车型客车重回值部分。

  PUT不是二个有惊无险的操作,因为它会修改(或创办)服务器上的状态,但它是幂等的。换句话说,倘若您利用PUT制造恐怕更新财富,然后重新调用,财富依然存在并且状态不会产生变化。

  例如,假设在财富增量计数器中调用PUT,那么这一个调用方法就不再是幂等的。那种情况有时候会发生,且恐怕能够表明它是非幂等性的。然则,提出维持PUT请求的幂等性。并强烈提议非幂等性的乞求使用POST。

POST

  POST请求日常被用来创设新的能源,尤其是被用来创建从属能源。从属能源即归属于其余能源(如父财富)的财富。换句话说,当创制3个新能源时,POST请求发送给父能源,服务端负责将新能源与父能源拓展关联,并分配三个ID(新能源的U奥迪Q7I),等等。

  例如:

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

  当制造成功时,重回HTTP状态码20一,并顺便一个岗位头新闻,个中涵盖指向起首创设的能源的链接。

  POST请求既不是平安的又不是幂等的,由此它被定义为非幂等性财富请求。使用两个一律的POST请求很可能会促成创设五个包涵相同音信的能源。

POST

  POST请求常常被用于成立新的财富,尤其是被用来制造从属能源。从属能源即归属于其余财富(如父能源)的能源。换句话说,当创制七个新财富时,POST请求发送给父能源,服务端负责将新财富与父财富拓展关联,并分配三个ID(新财富的U凯雷德I),等等。

  例如:

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

  当创造成功时,重临HTTP状态码20一,并顺便3个职分头新闻,在那之中蕴含指向初步成立的能源的链接。

  POST请求既不是平安的又不是幂等的,由此它被定义为非幂等性财富请求。使用几个相同的POST请求很大概会促成创立多少个带有相同消息的能源。

PUT和POST的开创比较

  综上可得,大家提议使用POST来创制财富。当由客户端来控制新财富有着何等U中华VI(通过财富名称或ID)时,使用PUT:即只要客户端知道URubiconI(或财富ID)是怎么,则对该U中华VI使用PUT请求。不然,当由服务器或服务端来支配创立的能源的UHavalI时则运用POST请求。换句话说,当客户端在开创以前不通晓(或不能知晓)结果的UHighlanderI时,使用POST请求来创设新的能源。

PUT和POST的开创比较

  综上可得,大家提出采取POST来创立能源。当由客户端来控制新能源有着什么样U卡宴I(通过财富名称或ID)时,使用PUT:即只要客户端知道ULX570I(或能源ID)是怎么,则对该U景逸SUVI使用PUT请求。不然,当由服务器或服务端来支配成立的能源的UPAJEROI时则应用POST请求。换句话说,当客户端在开立此前不清楚(或不可能知晓)结果的U揽胜I时,使用POST请求来创制新的能源。

DELETE

  DELETE很不难明白。它被用来遵照UKugaI标识删除能源。

  例如:

  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肆(表示无内容)表示平素不响应体。总而言之,能够回去状态码20肆象征从没响应体,只怕重临状态码200并且附带JSON风格的响应体。

  依照HTTP规范,DELETE操作是幂等的。如若你对一个能源拓展DELETE操作,资源就被移除了。在财富上反复调用DELETE最后促成的结果都壹律:即能源被移除了。但只要将DELETE的操功能于计数器(财富内部),则DETELE将不再是幂等的。如前方所述,只要数据尚未被更新,总结和衡量的用法如故可被认为是幂等的。提议非幂等性的财富请求使用POST操作。

  然则,那里有一个关于DELETE幂等性的告诫。在叁个财富上第3回调用DELETE往往会回到40四(未找到),因为该能源已经被移除了,所以找不到了。那使得DELETE操作不再是幂等的。假使财富是从数据库中删除而不是被略去地标记为除去,那种状态需求适度迁就。

  下表计算出了最紧要HTTP的办法和财富U科雷傲I,以及推荐的再次来到值:

HTTP请求

/customers

/customers/{id}

GET

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

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

PUT

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

200(正确)或20四(无内容)。如若未有找到ID或ID无效则赶回40肆(未找到)。

POST

20壹(创造),带有链接到/customers/{id}的职责头音讯,包蕴新的ID。

404(未找到)

DELETE

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

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

 

DELETE

  DELETE很不难精通。它被用来依照U奥迪Q5I标识删除能源。

  例如:

  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状态码20四(表示无内容)表示不曾响应体。由此可知,能够回来状态码20四代表从未响应体,也许再次回到状态码200并且附带JSON风格的响应体。

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

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

  下表总计出了第一HTTP的方法和资源U昂科威I,以及推荐的重返值:

HTTP请求

/customers

/customers/{id}

GET

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

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

PUT

404(未找到),除非你想在全路集合中创新/替换每一个财富。

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

POST

20一(创制),带有链接到/customers/{id}的职分头消息,包括新的ID。

404(未找到)

DELETE

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

200(正确)。假使未有找到ID或ID无效则赶回404(未找到)。

 

财富命名

  除了适本地动用HTTP动词,在开创一个方可清楚的、易于使用的Web服务API时,能源命名能够说是最具有争议和最要紧的概念。2个好的财富命名,它所对应的API看起来更加直观并且易于使用。相反,如若命名不佳,同样的API会令人觉得很鲁钝并且难以明白和行使。当您须要为您的新API创立财富U汉兰达L时,那里有壹些小技巧值得借鉴。

  从本质上讲,1个RESTFul
API末了都能够被简单地作为是一批UMuranoI的成团,HTTP调用那些U福特ExplorerI以及1些用JSON和(或)XML表示的能源,它们中有那一个富含了相互关联的链接。RESTful的可寻址能力根本依赖U奥迪Q3I。各样财富都有本身的地点或U宝马7系I——服务器能提供的每2个实用的消息都能够看做能源来公开。统一接口的标准化部分地因此UCR-VI和HTTP动词的构成来缓解,并符合利用规范和平条约定。

  在决定你系统中要利用的能源时,使用名词来命名这个财富,而不是用动词或动作来定名。换句话说,三个RESTful
UPAJEROI应该提到到3个有血有肉的财富,而不是事关到三个动作。别的,名词还有着部分动词没有的品质,那也是另二个明显的要素。

  一些能源的例子:

  • 系统的用户
  • 学员注册的教程
  • 2个用户帖子的时光轴
  • 关爱其余用户的用户
  • 1篇关于骑马的文章

  服务套件中的每一个财富最少有3个UPAJEROI来标识。借使这些U福特ExplorerI能表示肯定的意思并且可以尽量描述它所表示的能源,那么它就是3个最佳的命名。UTiguanI应该拥有可预测性和支行结构,那将带动升高它们的可掌握性和可用性的:可预测指的是财富应该和名称保持一致;而分层指的是数据有所关系上的构造。那并非REST规则或正规,但是它加重了对API的概念。

  RESTful
API是提供给消费端的。U宝马X5I的称号和协会应该将它所公布的意思传达给消费者。平常大家很难知晓数据的界线是如何,但是从你的数量上您应当很有很大恐怕去品味找到要回来给客户端的数码是什么样。API是为客户端而安顿的,而不是为您的数额。

  若是大家今后要讲述一个包蕴客户、订单,列表项,产品等职能的订单系统。考虑一下大家该怎么来讲述在那么些服务中所涉及到的财富的U纳瓦拉Is:

财富命名

  除了适本地选拔HTTP动词,在开立二个方可见晓的、易于使用的Web服务API时,财富命名能够说是最富有争议和最根本的定义。1个好的财富命名,它所对应的API看起来越来越直观并且易于使用。相反,若是命名倒霉,同样的API会让人深感很愚钝并且难以通晓和应用。当你须要为你的新API创立财富U奥德赛L时,这里有一部分小技巧值得借鉴。

  从本质上讲,贰个RESTFul
API最后都能够被简单地作为是一批U卡宴I的汇聚,HTTP调用这个U奥迪Q5I以及一些用JSON和(或)XML表示的财富,它们中有很多包罗了互动关系的链接。RESTful的可寻址能力主要信赖U奔驰G级I。每一种财富都有谈得来的地点或U奥迪Q7I——服务器能提供的每贰个立见功用的音信都能够作为财富来公开。统1接口的口径部分地经过URubiconI和HTTP动词的咬合来缓解,并符合利用正规和预订。

  在支配你系统中要动用的能源时,使用名词来命名那几个能源,而不是用动词或动作来定名。换句话说,3个RESTful
ULX570I应该提到到一个实际的能源,而不是关联到一个动作。其它,名词还存有部分动词未有的习性,那也是另三个妇孺皆知的因素。

  壹些财富的事例:

  • 系统的用户
  • 学员注册的学科
  • 2个用户帖子的岁月轴
  • 关心别的用户的用户
  • 一篇有关骑马的作品

  服务套件中的各种财富最少有八个U大切诺基I来标识。若是这些USportageI能表示肯定的意思并且能够丰富描述它所代表的能源,那么它正是贰个最棒的命名。U奥德赛I应该具有可预测性和支行结构,那将促进增加它们的可了解性和可用性的:可预测指的是财富应该和称号保持壹致;而分层指的是数码有所关系上的协会。那并非REST规则或规范,可是它加重了对API的概念。

  RESTful
API是提须要消费端的。U福睿斯I的名称和结构应该将它所发挥的意思传达给买主。平时大家很难通晓数据的分界是什么样,不过从您的数码上您应该很有不小希望去尝试找到要回到给客户端的多少是怎样。API是为客户端而设计的,而不是为你的多寡。

  如若大家未来要描述一个囊括客户、订单,列表项,产品等功效的订单系统。思量一下我们该怎么来讲述在这么些服务中所涉及到的财富的URubiconIs:

资源URI示例

  为了在系统中插入(创设)2个新的用户,大家能够运用:

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

 

  读取编号为332四伍的用户音信:

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

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

 

  上边是对产品有关的UTiguanI的壹部分建议:

  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恐怕不够直观,下边那些U哈弗I则更清楚壹些:

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

  以后大家精晓它是为编号33245的用户创设一个订单。

 

  那上面这一个请求重临的是什么啊?

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

  也许是三个号码为33245的用户所成立或具备的订单列表。注意:我们能够遮挡对该ULX570I举办DELETE或PUT请求,因为它的操作对象是四个集合。

 

  继续长远,这上面这几个U汉兰达I的呼吁又象征怎么样吧?

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

  恐怕是(为编号33二肆伍的用户)增加3个号码为876九的订单条目。没有错!假如采取GET方式呼吁这些U大切诺基I,则会重临那几个订单的富有条条框框。不过,假设那些条款与用户音信非亲非故,大家将会提供POST
www.example.com/orders/8769/lineitems
这个URI。

  从重返的这一个条款来看,钦定的能源只怕会有四个U兰德HighlanderIs,所以我们也许也急要求提供那样二个U奥迪Q3I
GET
http://www.example.com/orders/8769
,用来在不精通用户ID的状态下基于订单ID来查询订单。

 

  更进一步:

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

  恐怕只回去同个订单中的第二个条文。

  今后您应该明白什么是分层构造了。它们并不是严俊的平整,只是为了确定保证在您的劳务中那个强制的组织能够更易于被用户所知道。与全数软件开发中的技能1样,命名是成功的第三。

  

  多看有些API的示范并学会控制那么些技能,和您的队友1起来完善你API财富的UKoleosIs。那里有1些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

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

 

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

  壹种方案是:

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

  那种方法能够用来成立订单,但贫乏相应的用户数据。

  

  因为大家想为用户创设1个订单(注意之间的关联),这么些UHavalI恐怕不够直观,下面这几个URubiconI则更鲜爱他美些:

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

  未来大家精通它是为编号3324伍的用户创设二个订单。

 

  那下边这么些请求重回的是怎么着吧?

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

  只怕是贰个号码为33二4五的用户所创办或持有的订单列表。注意:大家得以屏蔽对该URI进行DELETE或PUT请求,因为它的操作对象是一个集合。

 

  继续深切,那上面那个UTucsonI的伸手又表示怎样吗?

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

  恐怕是(为编号33二肆伍的用户)扩张二个号码为876玖的订单条目。没有错!要是运用GET格局呼吁这一个U奇骏I,则会回到这几个订单的兼具条条框框。但是,假使这一个条款与用户新闻非亲非故,我们将会提供POST
www.example.com/orders/8769/lineitems
这个URI。

  从重返的那么些条款来看,钦赐的财富或许会有多个UHighlanderIs,所以我们大概也供给要提供那样3个UBMWX三I
GET
http://www.example.com/orders/8769
,用来在不知情用户ID的动静下基于订单ID来查询订单。

 

  更进一步:

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

  大概只回去同个订单中的首个条款。

  未来您应当明白什么是分层组织了。它们并不是严厉的条条框框,只是为了保险在您的劳动中这几个强制的组织能够更易于被用户所掌握。与有着软件开发中的技能一样,命名是成功的重大。

  

  多看有的API的示范并学会控制这个技巧,和您的队友壹起来宏观你API能源的U猎豹CS陆Is。那里有一部分APIs的事例:

能源命名的反例

  前边我们已经研究过局地相宜的能源命名的例子,但是有时一些反面包车型地铁例证也很有教育意义。上面是局地不太具有RESTful风格的财富U卡宴Is,看起来相比混乱。那几个都以荒唐的例证! 

  首先,1些serivices往往选拔单一的UPAJEROI来钦定服务接口,然后经过询问参数来钦赐HTTP请求的动作。例如,要更新编号1234伍的用户音讯,带有JSON
body的央浼或然是这么:

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

  就算地点U汉兰达L中的”services”的那个节点是1个名词,但以此U陆风X8L不是自解释的,因为对于具有的伸手而言,该URI的层级结构都以千篇1律的。其它,它使用GET作为HTTP动词来推行二个立异操作,那简直正是反人类(甚至是生命垂危的)。

  上边是此外1个翻新用户的操作的例证:

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

  以及它的三个变种:

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

  你会平时见到在任何开发者的服务套件中有很多这么的用法。能够看来,那么些开发者试图去创立RESTful的能源名称,而且早已有了有的升华。不过你还能够够分辨出ULANDL中的动词短语。注意,在那个U福睿斯L中大家不必要”update”那么些词,因为我们得以凭借HTTP动词来成功操作。上面那些ULacrosseL正好表达了那一点:

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

  这些请求同时设有PUT和”update”,那会对顾客发生吸引!这里的”update”指的是贰个财富吗?由此,这里我们费些口舌也是梦想您可见知情……

财富命名的反例

  后面大家早就商量过一些适度的能源命名的事例,可是有时1些反面包车型地铁例子也很有教育意义。下边是有的不太具有RESTful风格的财富ULANDIs,看起来相比散乱。这个都以不当的事例! 

  首先,1些serivices往往使用单1的U奥迪Q伍I来钦定服务接口,然后经过询问参数来钦赐HTTP请求的动作。例如,要翻新编号123四五的用户消息,带有JSON
body的伸手恐怕是那样:

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

  就算地点UHummerH二L中的”services”的这些节点是三个名词,但那么些U昂CoraL不是自解释的,因为对此全体的乞求而言,该U奥迪Q5I的层级结构都以一模一样的。别的,它接纳GET作为HTTP动词来实施二个更新操作,那简直就是反人类(甚至是高危的)。

  上面是其余2个更新用户的操作的事例:

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

  以及它的3个变种:

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

  你会时不时看看在其它开发者的劳务套件中有许多那样的用法。能够见见,这几个开发者试图去创建RESTful的能源名称,而且早已有了有些提升。但是你依旧能够辨识出U奥迪Q5L中的动词短语。注意,在这么些U猎豹CS陆L中我们不要求”update”这么些词,因为大家得以依赖HTTP动词来形成操作。上边那一个U逍客L正好表达了那或多或少:

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

  这么些请求同时存在PUT和”update”,那会对消费者发生吸引!那里的”update”指的是3个财富吗?因而,这里大家费些口舌也是目的在于您可见驾驭……

复数

  让我们来研讨一下复数和“单数”的争执…还没听别人讲过?但那种争议确实存在,事实上它能够归咎为这些题材……

  在你的层级结构中U兰德福特ExplorerI节点是不是必要被取名称叫单数或复数方式吗?举个例子,你用来寻觅用户能源的U奥迪Q3I的命名是还是不是必要像上面那样:

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

  或者:

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

  三种方法都没难题,但日常大家都会挑选使用复数命名,以使得你的API
ULX570I在具有的HTTP方法中保持一致。原因是基于那样壹种思虑:customers是劳动套件中的贰个凑合,而ID33二四五的这几个用户则是其1集合中的其中二个。

  依照这几个规则,贰个使用复数方式的多节点的UPAJEROI会是那般(注意粗体部分):

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

  “customers”、“orders”以及“lineitems”那几个URAV4I节点都选拔的是复数情势。

  那意味你的种种根财富只供给四个着力的U凯雷德L就足以了,多少个用以成立集合内的能源,另3个用来根据标识符获取、更新和删除财富。例如,以customers为例,创设财富得以采用上面包车型大巴ULANDL实行操作:

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

  而读取、更新和删除财富,使用下边包车型地铁U途胜L操作:

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

  正如前方提到的,给定的财富大概有多个U奥迪Q五I,但作为3个相当的小的完全的增删改查功能,利用多个大致的URAV4I来拍卖就够了。

  或者你会问:是还是不是在稍微情形下复数未有意思?嗯,事实上是这么的。当未有集合概念的时候(此时复数未有意思)。换句话说,当能源唯有贰个的气象下,使用单数能源名称也是能够的——即一个单一的财富。例如,倘诺有四个纯粹的完整布置能源,你能够接纳三个单数名称来代表:

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

  注意那里贫乏configuration的ID以及HTTP动词POST的用法。假如每种用户有贰个陈设来说,那么那些ULX570L会是这么:

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

  同样令人瞩目这里未有点名configuration的ID,以及从未给定POST动词的用法。在那七个例子中,恐怕也会有人以为选用POST是立见成效的。好吧…

 

复数

  让我们来钻探一下复数和“单数”的争辨…还没听他们讲过?但那种争议确实存在,事实上它可以归纳为那一个标题……

  在你的层级结构中U奥德赛I节点是不是需求被取名称为单数或复数格局吗?举个例子,你用来搜寻用户能源的UCRUISERI的命名是或不是须要像上边那样:

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

  或者:

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

  三种方法都没难题,但1般我们都会选拔选用复数命名,以使得你的API
U翼虎I在具备的HTTP方法中保持壹致。原因是依照那样一种牵记:customers是服务套件中的八个聚集,而ID33二肆伍的那几个用户则是以此集合中的在那之中三个。

  依据那一个规则,多个施用复数格局的多节点的U哈弗I会是如此(注意粗体部分):

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

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

  那意味你的每种根财富只供给多个主旨的UPRADOL就能够了,二个用以创建集合内的能源,另贰个用来依据标识符获取、更新和删除财富。例如,以customers为例,创造财富得以采取下边包车型客车UOdysseyL进行操作:

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

  而读取、更新和删除能源,使用下边包车型地铁U奥迪Q5L操作:

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

  正如前方提到的,给定的能源大概有八个U奥迪Q3I,但作为三个小小的的一体化的增删改查功效,利用八个不难的UKoleosI来处理就够了。

  或许你会问:是不是在稍微境况下复数未有意义?嗯,事实上是这么的。当未有集合概念的时候(此时复数没有意义)。换句话说,当能源只有1个的情事下,使用单数财富名称也是能够的——即3个单壹的能源。例如,若是有多少个纯粹的欧洲经济共同体布局能源,你能够利用贰个单数名称来代表:

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

  注意那里贫乏configuration的ID以及HTTP动词POST的用法。要是每一个用户有3个配备来说,那么那个U悍马H贰L会是这么:

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

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

 

回去表征

  正如前方提到的,RESTful接口帮助七种财富特色,包蕴JSON和XML,以及被卷入的JSON和XML。提出JSON作为私下认可表征,可是服务端应该允许客户端钦点其余表征。

  对于客户端请求的性状格式,大家能够在Accept头通过文件扩张名来开始展览点名,也得以通过query-string等此外措施来钦命。理想图景下,服务端能够支撑具备那个点子。不过,现在正规更赞成于通过类似于文件扩充名的不2法门来进展点名。由此,提议服务端至少要求辅助使用文件扩大名的方法,例如“.json”,“.xml”以及它们的包装版本“.wjon”,“.wxml”。

  通过这种艺术,在UQX56I中钦命重返表征的格式,能够拉长UGL450L的可知性。例如,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为123四伍的customer数据均为JSON格式,那是服务端的默许格式。

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

  假设服务端扶助的话,以上请求重临的ID为12345的customer数据为XML格式。尽管该服务器不援助XML格式的财富,将回到2个HTTP
40肆的不当。

  使用HTTP
Accept头被大规模认为是一种更优雅的法门,并且符合HTTP的专业和意义,客户端能够通过那种艺术来报告HTTP服务端它们可支撑的数据类型有啥样。可是,为了利用Accept头,服务端要同时协理封装和未封装的响应,你必须兑现自定义的类别——因为那些格式不是正经的品类。那大大增添了客户端和服务端的复杂。请参见LANDFC
261陆的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中钦定再次来到表征的格式,能够增加UTucsonL的可见性。例如,GET
http://www.example.com/customers.xml
将重返customer列表的XML格式的特征。同样,GET
http://www.example.com/customers.json
将回到1个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为1234五的customer数据为XML格式。即便该服务器不帮忙XML格式的财富,将回来多个HTTP
404的失实。

  使用HTTP
Accept头被大规模认为是1种更优雅的措施,并且符合HTTP的科班和意义,客户端能够透过那种措施来报告HTTP服务端它们可支撑的数据类型有何样。可是,为了利用Accept头,服务端要同时扶助封装和未封装的响应,你必须兑现自定义的体系——因为这个格式不是正经的品类。那大大扩大了客户端和服务端的复杂。请参见本田CR-VFC
261陆的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是什么”壹节中也关系过。

  遵照RoyFielding在他的博客中的描述(http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertextdriven),REST接口中最主要的部分是超文本的使用。此外,他还提出,在交付任何有关的音信在此以前,3个API应该是可用和可清楚的。也正是说,一个API应当能够由此其链接导航到数量的逐壹部分。不提议只回去纯数据。

  可是当下的产业界先驱们并从未平常应用那种做法,那反映了HATEOAS仅仅在成熟度模型中的使用率越来越高。纵观众多的服务体系,它们大多重返越多的多少,而回到的链接却很少(也许未有)。那是违背Fielding的REST约定的。Fielding说:“音信的每多少个可寻址单元都带领三个地点……查询结果应该展现为二个包罗摘要消息的链接清单,而不是目的数组。”

  另一方面,简单残暴地将全部链接集合再次回到会大大影响互联网带宽。在事实上意况中,根据所需的尺度或使用情形,API接口的通讯量要依照服务器响应中中国足球球组织一级联赛文本链接所包括的“摘要”数量来抵消。

  同时,丰盛利用HATEOAS恐怕会大增实现的纷纭,并对劳务客户端产生强烈的承受,这一定于下跌了客户端和劳动器端开发人员的生产力。因而,当务之急是要平衡超链接服务实施和现有可用能源之间的难点。

  超链接最小化的做法是在最大限度地压缩客户端和服务器之间的耦合的还要,升高服务端的可用性、可操纵性和可精通性。那几个最小化提议是:通过POST创制能源并从GET请求重临集合,对于有分页的情况后面大家会涉及。

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

  REST指点标准之壹(依据联合接口规范)是application的动静通过hypertext(超文本)来传输。那正是我们常常所说的Hypertext
As The Engine of Application State
(即HATEOAS,用超文本来作为应用程序状态机),大家在“REST是什么”1节中也提到过。

  依照Roy菲尔德ing在他的博客中的描述(http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertextdriven),REST接口中最重点的片段是超文本的施用。其余,他还建议,在交付任何有关的音讯在此之前,三个API应该是可用和可精晓的。也正是说,二个API应当可以通过其链接导航到多少的依次部分。不提议只回去纯数据。

  不过当下的产业界先驱们并不曾日常应用那种做法,这反映了HATEOAS仅仅在成熟度模型中的使用率更加高。纵听众多的服务种类,它们基本上重临越多的数码,而回到的链接却很少(大概未有)。那是反其道而行之Fielding的REST约定的。菲尔德ing说:“新闻的每二个可寻址单元都教导二个地址……查询结果应当呈现为二个涵盖摘要新闻的链接清单,而不是指标数组。”

  另1方面,不难无情地将全方位链接集合再次来到会大大影响网络带宽。在实况中,根据所需的规格或利用状态,API接口的通讯量要依据服务器响应中国足球组织一级联赛文本链接所包蕴的“摘要”数量来抵消。

  同时,充裕利用HATEOAS只怕会大增完结的错综复杂,并对服务客户端产生显著的负责,这一定于降低了客户端和劳务器端开发人士的生产力。由此,当务之急是要平衡超链接服务推行和现有可用财富之间的标题。

  超链接最小化的做法是在最大限度地收缩客户端和服务器之间的耦合的还要,进步服务端的可用性、可操纵性和可明白性。这一个最小化提出是:通过POST创造财富并从GET请求再次来到集合,对于有分页的景况前边大家会涉及。

小小的化链接推荐

  在create的用例中,新建财富的U中华VI(链接)应该在Location响应头中回到,且响应大旨是空的——大概只包罗新建能源的ID。

  对于从服务端重临的特征集合,各种表征应该在它的链接集合中带走三个非常小的“本人”链接属性。为了便利分页操作,其它的链接能够置身2个独自的链接集合中回到,须要时能够分包“第三页”、“上一页”、“下1页”、“最后一页”等信息。

  参照下文链接格式一部分的例证获取更多消息。

小小的化链接推荐

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

  对于从服务端再次来到的特色集合,每一种表征应该在它的链接集合中带走3个纤维的“本身”链接属性。为了便利分页操作,其余的链接能够置身二个独门的链接集合中回到,供给时能够分包“第三页”、“上1页”、“下一页”、“最终一页”等信息。

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

链接格式

  参照整个链接格式的正式,提出服从1些接近Atom、AtomPub或Xlink的作风。JSON-LD也不易,但并未被大规模运用(假诺已经被用过)。近日行业内部最广大的主意是行使含有”rel”成分和含有能源全体UTucsonI的”href”成分的Atom链接格式,不分包其余身份验证或询问字符串参数。”rel”成分得以涵盖标准值”alternate”、”related”、”self”、”enclosure”和”via”,还有分页链接的“第二页”、“上1页”、“下一页”,“最后壹页”。在急需时能够自定义并丰盛应用它们。

  一些XML
Atom格式的概念对于用JSON格式表示的链接来说是低效的。例如,METHOD属性对于一个RESTful财富来说是不需求的,因为对此多少个加以的能源,在装有协理的HTTP方法(CRUD行为)中,能源的UHummerH二I都以均等的——所以单独列出这几个是从没有过供给的。

  让我们举1些有血有肉的例子来更是求证那或多或少。上边是调用成立新能源的伸手后的响应:

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

  上面是响应头集合中隐含创立新财富的UPAJEROI的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请求获取一个不包罗分页的性状集合的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响应(每页突显三项),大家提交第二页的数额:

{
  "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。二个便是data对象中所包罗的成团(那个也是接口要回到给客户端的数码表征集合),在那之中的每壹项至少要包涵一个对准“自己(self)”的links集合;另一个则是2个独立的靶子links,当中包含和分页相关的链接,该部分的内容适用于全部集合。

  对于由此POST请求创造财富的情形,须要在响应头中包括1个提到新建对象链接的Location

链接格式

  参照整个链接格式的专业,建议坚守壹些近乎Atom、AtomPub或Xlink的品格。JSON-LD也不错,但并未有被周围采取(假若已经被用过)。最近标准最广泛的方法是行使含有”rel”成分和带有能源全体UXC90I的”href”成分的Atom链接格式,不分包别的身份验证或询问字符串参数。”rel”成分得以涵盖标准值”alternate”、”related”、”self”、”enclosure”和”via”,还有分页链接的“第2页”、“上一页”、“下一页”,“最后一页”。在急需时方可自定义并丰裕应用它们。

  1些XML
Atom格式的定义对于用JSON格式表示的链接来说是对事情未有什么帮助的。例如,METHOD属性对于二个RESTful能源来说是不要求的,因为对此二个加以的能源,在拥有接济的HTTP方法(CRUD行为)中,能源的UCR-VI都是均等的——所以单独列出这个是绝非须求的。

  让大家举一些有血有肉的例子来特别表明那或多或少。下边是调用创制新财富的央求后的响应:

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

  下边是响应头集合中带有创设新财富的URI的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请求获取三个不包括分页的性状集合的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等。

  最终2个例证是透过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": [
    {
      "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对象中所包括的聚集(那些也是接口要回到给客户端的数额表征集合),个中的每一项至少要蕴涵2个对准“本身(self)”的links集合;另1个则是1个单独的靶子links,在那之中囊括和分页相关的链接,该部分的故事情节适用于全部集合。

  对于通过POST请求创立财富的情形,须要在响应头中包涵1个事关新建对象链接的Location

包装响应

   服务器能够在响应中同时再次来到HTTP状态码和body。有诸多JavaScript框架未有把HTTP状态响应码再次回到给最后的开发者,那频仍会促成客户端非常的小概依照景况码来分明具体的一颦一笑。其余,固然HTTP规范中有很三种响应码,可是往往只某个客户端会关心那些——日常大家只在乎”success”、”error”或”failture”。因而,将响应内容和响应状态码封装在包蕴响应音信的特点中,是有不能缺少的。

  OmniTI
实验室有那样二个提出,它被称呼JSEND响应。越多音信请参见http://labs.omniti.com/labs/jsend。此外2个提案是由DouglasCrockford提议的,能够查看那里http://www.json.org/JSONRequest.html

  这一个提案在实践中并未完全涵盖全体的景况。基本上,今后最佳的做法是服从以下属性封装常规(非JSONP)响应:

  • code——包括二个平头项指标HTTP响应状态码。
  • status——包括文本:”success”,”fail”或”error”。HTTP状态响应码在500-59九里边为”fail”,在400-49九里头为”error”,别的均为”success”(例如:响应状态码为一XX、二XX和三XX)。
  • message——当状态值为”fail”和”error”时有效,用于展示错误音讯。参照国际化(il八n)标准,它能够包含音讯号或然编码,能够只包含其中贰个,或然同时富含并用分隔符隔绝。
  • 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。其余2个提案是由DouglasCrockford提议的,可以查阅那里http://www.json.org/JSONRequest.html

  那么些提案在实践中并不曾完全涵盖全体的景观。基本上,未来最棒的做法是循途守辙以下属性封装常规(非JSONP)响应:

  • code——包蕴多个整数类型的HTTP响应状态码。
  • status——蕴涵文本:”success”,”fail”或”error”。HTTP状态响应码在500-59玖时期为”fail”,在400-49九中间为”error”,别的均为”success”(例如:响应状态码为1XX、2XX和三XX)。
  • message——当状态值为”fail”和”error”时有效,用于体现错误音讯。参照国际化(il八n)标准,它能够分包音信号恐怕编码,能够只含有个中二个,恐怕同时涵盖并用分隔符隔离。
  • 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汉兰达S)。JSONP或“填充的JSON”是一种采用形式,它提供了多少个格局请求来自分裂域中的服务器的多寡。其工作办法是从服务器再次来到任意的JavaScript代码,而不是JSON。客户端的响应由JavaScript解析器举办分析,而不是直接解析JSON数据。其它,CO揽胜S是1种web浏览器的技能标准,它为web服务器定义了1种艺术,从而允许服务器的财富得以被不相同域的网页访问。CO奇骏S被看作是JSONP的风行替代品,并且能够被有着现代浏览器补助。由此,不建议选拔JSONP。任何动静下,推荐选取CO普拉多S。

处理跨域难题

   大家都传说过关于浏览器的同源策略或同源性必要。它指的是浏览器只好请求当前正在彰显的站点的财富。例如,假如当前正值呈现的站点是www.Example1.com,则该站点不可能对www.Example.com倡议呼吁。显著那会影响站点访问服务器的方法。

  近期有三个被普遍接受的支撑跨域请求的艺术:JSONP和跨域能源共享(CO普拉多S)。JSONP或“填充的JSON”是1种选拔情势,它提供了2个格局请求来自分裂域中的服务器的数据。其工作章程是从服务器再次回到任意的JavaScript代码,而不是JSON。客户端的响应由JavaScript解析器实行分析,而不是直接解析JSON数据。其它,CO奇骏S是壹种web浏览器的技能标准,它为web服务器定义了壹种艺术,从而允许服务器的财富得以被分化域的网页访问。COSportageS被当做是JSONP的新型替代品,并且可以被有着现代浏览器协助。由此,不建议选择JSONP。任何动静下,推荐选择CO帕杰罗S。

支持CORS

  在服务端完毕CO冠道S相当粗略,只需求在发送响应时顺手HTTP头,例如: 

Access-Control-Allow-Origin: *

  只有在数据是公共使用的图景下才会将访问来源设置为”*”。大部分情状下,Access-Control-Allow-Origin头应该内定哪些域可以发起3个CO兰德酷路泽S请求。唯有须求跨域访问的UMuranoL才设置CO奥迪Q7S头。

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服务器上安排多个用空格分隔的域的列表。越多关于COMuranoS的剧情能够参照这里:http://enable-cors.org/

支持CORS

  在服务端实现CO中华VS很粗大略,只供给在发送响应时顺手HTTP头,例如: 

Access-Control-Allow-Origin: *

  唯有在数据是集体使用的景况下才会将做客来源设置为”*”。大多数景色下,Access-Control-Allow-Origin头应该钦命哪些域能够倡导七个CO兰德酷路泽S请求。唯有供给跨域访问的U悍马H二L才设置CO冠道S头。

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服务器上配置1个用空格分隔的域的列表。更多关于CO奥德赛S的剧情能够参照这里:http://enable-cors.org/

支持JSONP

  JSONP通过应用GET请求避开浏览器的范围,从而达成对富有服务的调用。其行事原理是请求方在伸手的URubiconL上添加多少个字符串查询参数(例如:jsonp=”jsonp_callback”),当中“jsonp”参数的值是JavaScript函数名,该函数在有响应重临时将会被调用。

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

  JSONP通常在部分不援助CO奔驰M级S的老旧浏览器中央银行使,借使要改成协理COPAJEROS的,会影响总体服务器的架构。或许我们也能够由此代理来落到实处JSONP。由此可见,JSONP正在被CO帕杰罗S所代替,大家应有尽大概地应用CO科雷傲S。

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

  1. 响应体必须封装成3个参数字传送递给jsonp中钦赐的JavaScript函数(例如:jsonp_callback(“<JSON
    response body>”))。
  2. 1味重临HTTP状态码200(OK),并且将真正的气象作为JSON响应中的1局地重临。

  其它,响应体中时常必须带有响应头。那使得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请求避开浏览器的范围,从而达成对负有服务的调用。其行事原理是请求方在央浼的UXC60L上添加一个字符串查询参数(例如:jsonp=”jsonp_callback”),个中“jsonp”参数的值是JavaScript函数名,该函数在有响应重临时将会被调用。

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

  JSONP经常在1部分不帮助CO福睿斯S的老旧浏览器中央银行使,尽管要改成匡助CO翼虎S的,会影响全体服务器的架构。大概大家也得以因此代理来贯彻JSONP。不问可见,JSONP正在被CO卡宴S所代替,大家相应尽或者地应用CO昂CoraS。

  为了在服务端援救JSONP,在JSONP字符串查询参数字传送递时,响应必需要履行以下这几个操作:

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

  其余,响应体中日常必须带有响应头。那使得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处理的角度来看,限制数据量也同等不可或缺,因为UI平常只好显示大数目汇总的一小部分数目。在数据集的增速不鲜明的状态下,限制暗许重回的数据量是很有至关重要的。以推特(TWTR.US)为例,要博得某些用户的推文(通过个人主页的年华轴),假若未有专门钦命,请求默许只会回来20条记下,固然系统最多能够回去200条记下。

  除了限制再次回到的数据量,大家还供给思虑如何对天意据集进行“分页”或下拉滚动操作。成立数量的“页码”,重回大数目列表的已知片段,然后标出数据的“前一页”和“后壹页”——这一表现被叫作分页。其它,大家恐怕也急需钦点响应上将包括如何字段或品质,从而限制重返值的多少,并且大家愿意最终能够透过特定值来进展询问操作,并对再次回到值进行排序。

  有三种主要的法子来还要限制查询结果和履行分页操作。首先,我们得以建立一个目录方案,它能够以页码为导向(请求中要付出每壹页的记录数及页码),可能以记录为导向(请求中平素交给第二条记下和尾声一条记下)来规定重回值的前奏地方。举个例子,那二种格局分别代表:“给出第四页(假如每页有20条记下)的记录”,或“给出第100到第320条的笔录”。

  服务端将基于运作机制来举行切分。某些UI工具,比如Dojo
JSON会选拔模仿HTTP规范使用字节范围。假使服务端匡助out of
box(即开箱即用效应),则前端UI工具和后端服务时期无需任何转换,那样使用起来会很方便。

  下文将介绍一种艺术,既能够支持Dojo那样的分页格局(在请求头中提交记录的范围),也能帮衬使用字符串查询参数。那样一来服务端将变得进一步灵敏,既能够动用类似Dojo一样先进的UI工具集,也能够选择简单直接的链接和标签,而无需再为此增加复杂的开支工作。但如若服务不直接援救UI功用,能够设想不要在请求头中付出记录范围。

  要专门提出的是,大家并不引入在具有服务中利用查询、过滤和分页操作。并不是享有财富都暗许帮助那一个操作,唯有少数特定的财富才支撑。服务和财富的文书档案应当表明怎样接口援救那一个复杂的功用。

查询,过滤和分页

  对于大数据集,从带宽的角度来看,限制重回的数据量是老大主要的。而从UI处理的角度来看,限制数据量也①律关键,因为UI常常只可以显示大数额集中的一小部分数目。在数据集的增速不鲜明的景观下,限制暗许再次来到的数据量是很有要求的。以Instagram为例,要博得有个别用户的推文(通过个人主页的年月轴),假诺未有尤其钦命,请求私下认可只会回到20条记下,即便系统最多能够重临200条记下。

  除了限制再次来到的数据量,大家还需求思索怎么对天意据集举行“分页”或下拉滚动操作。成立数量的“页码”,重回大数据列表的已知片段,然后标出数据的“前1页”和“后一页”——那一作为被叫作分页。其余,大家可能也急需钦命响应军长包罗哪些字段或质量,从而限制再次来到值的数额,并且我们愿意最后能够透过一定值来进展询问操作,并对重返值进行排序。

  有二种关键的办法来还要限制查询结果和进行分页操作。首先,大家得以创制多个索引方案,它能够以页码为导向(请求中要付出每1页的记录数及页码),恐怕以记录为导向(请求中央直机关接提交第二条记下和尾声一条记下)来明确重返值的前奏地方。举个例子,那三种方法分别代表:“给出第陆页(如若每页有20条记下)的记录”,或“给出第柒0到第320条的笔录”。

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

  下文将介绍一种方法,既能够协助Dojo那样的分页格局(在请求头中付出记录的范围),也能辅助使用字符串查询参数。那样一来服务端将变得尤为灵敏,既能够使用类似Dojo一样先进的UI工具集,也可以应用简单直接的链接和标签,而无需再为此扩充复杂的花费工作。但假如服务不直接帮衬UI成效,能够设想不要在请求头中提交记录范围。

  要特别建议的是,大家并不引入在全数服务中运用查询、过滤和分页操作。并不是装有财富都暗中认可援救这么些操作,唯有少数特定的能源才支撑。服务和财富的文书档案应当表达如何接口支持这几个扑朔迷离的效率。

结果限制

  “给出第二到第四五条的笔录”,那种请求数据的方法和HTTP的字节范围规范更平等,因而我们得以用它来标识Range
header。而“从第三条记下早先,给出最多20条记下”那种艺术更易于阅读和掌握,因而大家经常会用字符串查询参数的艺术来表示。

  综上所述,推荐既辅助接纳HTTP Range
header,也支撑采用字符串查询参数——offset(偏移量)和limit(限制),然后在服务端对响应结果开展界定。注意,固然还要辅助那二种方法,那么字符串查询参数的预先级要当先Range
header。

  那里您大概会有个问号:“那三种形式效果相似,不过回去的数目不完全1致。那会不会令人歪曲呢?”恩…那是多个难点。首先要应对的是,这诚然会令人歪曲。关键是,字符串查询参数看起来更加清晰易懂,在营造和分析时尤其便利。而Range
header则越来越多是由机械来利用(偏向于底层),它更是契合HTTP使用正规。

  同理可得,解析Range
header的工作会扩展复杂度,相应的客户端在构建请求时也需求进行部分拍卖。而选拔单独的limit和offset参数会更为不难通晓和营造,并且不供给对开发职员有越来越多的须要。

结果限制

  “给出第一到第陆5条的笔录”,那种请求数据的主意和HTTP的字节范围规范更平等,因而大家得以用它来标识Range
header。而“从第三条记下发轫,给出最多20条记下”那种办法更易于阅读和精通,因而我们平时会用字符串查询参数的法子来表示。

  综上所述,推荐既支持采纳HTTP Range
header,也支撑采用字符串查询参数——offset(偏移量)和limit(限制),然后在服务端对响应结果开始展览界定。注意,假设还要匡助那两种方法,那么字符串查询参数的优先级要高于Range
header。

  这里您大概会有个问号:“那二种方法效果相似,不过回去的数目不完全1致。这会不会令人歪曲呢?”恩…那是五个难题。首先要应对的是,那真的会令人歪曲。关键是,字符串查询参数看起来尤其清晰易懂,在创设和剖析时尤其有益。而Range
header则越来越多是由机械来行使(偏向于底层),它更是切合HTTP使用标准。

  综上说述,解析Range
header的工作会增添复杂度,相应的客户端在营造请求时也要求进行部分甩卖。而接纳单独的limit和offset参数会越加便于驾驭和创设,并且不供给对开发职员有越来越多的要求。

用范围标记实行限制

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

  Range: items=0-24

  注意记录是从0开头的总是字段,HTTP规范中表达了如何接纳Range
header来请求字节。约等于说,如若要乞请数据集中的率先条记下,范围应当从0初步算起。上述的伸手将会回去前贰几个记录,假使数据汇总至少有25条记下。

  而在服务端,通过检查请求的Range
header来鲜明该重回哪些记录。只要Range
header存在,就会有贰个简练的正则表明式(如”items=(\d+)-(\d+)”)对其进展辨析,来获取要寻找的范围值。

用范围标记实行界定

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

  Range: items=0-24

  注意记录是从0先河的接连字段,HTTP规范中证实了怎么行使Range
header来请求字节。相当于说,即使要请求数据汇总的首先条记下,范围应该从0起首算起。上述的伸手将会回到前二两个记录,固然数据集中至少有二5条记下。

  而在服务端,通过检查请求的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值,可是这一个参数的使用都要求在文书档案中进行表达。

传说范围的响应

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

  Content-Range: items 0-24/66

  注意那里的总记录数(如本例中的6陆)不是从0初叶总计的。借使要央求数据汇总的末梢几条记下,Content-Range
header的剧情应该是那样:

  Content-Range: items 40-65/66

  根据HTTP的科班,倘诺响应时总记录数未知或难以计算,也足以用星号(”*”)来顶替(如本例中的66)。本例中响应头也可那般写:

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

  可是要留意,Dojo或一些任何的UI工具只怕不援救该符号。

根据范围的响应

  对叁个根据范围的央浼来说,无论是通过HTTP的Range
header依然通过字符串查询参数,服务端都应有有3个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或1些其余的UI工具恐怕不支持该符号。

分页

  上述方法通过请求方钦点数据集的限量来界定再次来到结果,从而完结分页功效。上边包车型地铁例证中一起有6六条记下,假使每页二伍条记下,要出示第2页数据,Range
header的内容如下:

  Range: items=25-49

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

  GET …?offset=25&limit=25

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

  Content-Range: 25-49/66

  在大部分意况下,那种分页方式都并未难题。但偶尔会有这种情景,就是要重返的笔录数据不恐怕直接代表成数据集中的行号。还有正是有个别数据集的成形非常快,不断会有新的多少插入到多少集中,那样必然会导致分页出现难点,一些再次的数据也许会油可是生在分歧的页中。

  按日期排列的数据集(例如Instagramfeed)就是一种常见的状态。即使你还能对数码开始展览分页,但有时用”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*

  有关在不一致景色对时间戳的格式化处理,请参见下文的“日期/时间拍卖”。

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

  Content-Range: 0-19/4125

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

分页

  上述形式经过请求方内定数据集的限定来限制重临结果,从而完成分页功能。上边的事例中累计有6陆条记下,要是每页二伍条记下,要呈现第三页数据,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*

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

  假如请求时髦未点名要赶回的数目范围,服务端重临了1组暗许数据或限制的最大数据集,那么服务端同时也应该在重返结果中包括Content-Range
header来和客户端进行确认。以地点个人主页的岁月轴为例,无论客户端是或不是内定了Range
header,服务端每一次都只回去20条记下。此时,服务端响应的Content-Range
header应该包罗如下内容:

  Content-Range: 0-19/4125

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

结果的过滤和排序

  针对再次来到结果,还需求思索怎样在服务端对数码举办过滤和排列,以及如何按钦定的次第对子数据开始展览搜寻。这一个操作能够与分页、结果限制,以及字符串查询参数filter和sort等相结合,能够兑现强大的数据检索效能。

  再强调一遍,过滤和排序都以繁体的操作,不要求暗许提须求全部的财富。下文将介绍怎么着财富须求提供过滤和排序。

结果的过滤和排序

  针对重返结果,还供给考虑怎么在服务端对数据开始展览过滤和排列,以及如何按钦命的顺序对子数据开始展览检索。这一个操作能够与分页、结果限制,以及字符串查询参数filter和sort等相结合,能够兑现强大的数据检索功能。

  再强调2次,过滤和排序都以扑朔迷离的操作,不要求私下认可提须求拥有的能源。下文将介绍怎样能源供给提供过滤和排序。

过滤

  在本文中,过滤被定义为“通过特定的规范来规定必供给回来的多寡,从而减弱重临的数据”。假如服务端援救一套完整的比较运算符和复杂性的尺度分外,过滤操作将变得十分复杂。然则我们一般会使用一些粗略的表明式,如starts-with(以…初始)或contains(蕴涵)来进展相称,以保险重回数据的完整性。

  在我们开首研商过滤的字符串查询参数此前,必须先明了为何要动用单个参数而不是多少个字符串查询参数。从根本上来说是为了减小参数名称的冲突。大家早已有offsetlimitsort(见下文)参数了。假诺也许的话还会有jsonpformat标识符,或然还会有afterbefore参数,那一个都以在本文中涉及过的字符串查询参数。字符串查询中央银行使的参数更多,就越大概造成参数名称的争执,而选取单个过滤参数则会将争辩的大概降到最低。

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

  通过引进一组广泛的、公认的分隔符,用于过滤的表明式可以以老大直观的样式被运用。用那些分隔符来设置过滤查询参数的值,这个分隔符所创设的参数名/值对可以进一步简单地棉被和衣服务端解析并抓实数据查询的属性。近来已有的分隔符包含用来分隔各个过滤短语的竖线(”|”)和用来分隔参数名和值的双冒号(”::”)。那套分隔符丰硕唯一,并符合一大半情状,同时用它来塑造的字符串查询参数也尤其简单精晓。下边将用2个简单易行的例子来介绍它的用法。如果大家想要给名称为“托德”的用户们发送请求,他们住在里昂,有着“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)。

过滤

  在本文中,过滤被定义为“通过一定的规则来明确必须求赶回的数额,从而收缩重回的数额”。倘若服务端援助壹套完整的可比运算符和复杂性的原则合营,过滤操作将变得分外复杂。不过我们常见会选拔部分简练的表明式,如starts-with(以…开头)或contains(包罗)来拓展相配,以担保重回数据的完整性。

  在大家起头谈论过滤的字符串查询参数在此以前,必须先知道为什么要动用单个参数而不是多个字符串查询参数。从根本上来说是为了减小参数名称的争持。我们已经有offsetlimitsort(见下文)参数了。假如恐怕的话还会有jsonpformat标识符,只怕还会有afterbefore参数,那些都以在本文中涉嫌过的字符串查询参数。字符串查询中选拔的参数越多,就越也许造成参数名称的抵触,而使用单个过滤参数则会将冲突的可能降到最低。

  其它,从服务端也很不难仅经过单个的filter参数来判断请求方是或不是供给多少过滤效果。若是查询需求的复杂度扩张,单个参数将更具备灵活性——可以团结树立1套功用1体化的询问语法(详见下文OData注释或访问http://www.odata.org)。

  通过引进一组广泛的、公认的分隔符,用于过滤的表明式能够以老大直观的款式被选择。用这个分隔符来设置过滤查询参数的值,这一个分隔符所创制的参数名/值对可以尤其便于地被服务端解析并做实多少查询的习性。近来已有的分隔符包蕴用来分隔每种过滤短语的竖线(”|”)和用来分隔参数名和值的双冒号(”::”)。那套分隔符丰富唯一,并符合大部分动静,同时用它来营造的字符串查询参数也进一步便于通晓。上面将用三个简短的例证来介绍它的用法。假若大家想要给名字为“托德”的用户们发送请求,他们住在明尼阿波利斯,有着“Grand
Poobah”之称。用字符串查询参数完结的请求UCR-VI如下:

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

排序

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

  同样,大家这里只思量部分相比简单的情事。推荐应用排序字符串查询参数,它包涵了1组用分隔符分隔的属性名。具体做法是,暗中同意对每种属性名按升序排列,假若属性名有前缀”-“,则按降序排列。用竖线(”|”)分隔每一种属性名,那和前边过滤效果中的参数名/值对的做法一点差异也未有于。

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

  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可能在少数时候必要变更重临数据的格式和情节,而那也将促成消费端的1对变更,大家相应防止实香港行政局地第二的调整。将API举行版本化管理是幸免那种根本变化的一种有效办法。

劳动版本管理

   坦率地讲,1谈起版本就会令人认为很狼狈,很劳碌,不太容易,甚至会令人觉得伤心——因为那会追加API的复杂度,并还要或然会对客户端爆发1些影响。由此,在API的规划中要尽量幸免多个不一致的本子。

  不援救版本,不将版本控制作为不好的API设计的注重性。假如你在APIs的设计中引进版本,这迟早都会让您抓狂。由于重临的多寡通过JSON来表现,客户端会由于分裂的本子而接受到分化的属性。那样就会存在部分题材,如从内容笔者和验证规则方面改变了贰个已存在的性质的含义。

  当然,大家无能为力幸免API大概在少数时候供给转移再次来到数据的格式和情节,而那也将促成消费端的有的转移,我们相应防止进行局地最首要的调整。将API进行版本化管理是幸免那种根本变化的壹种有效办法。

由此内容协商协理版本管理

  未来,版本管理通过U揽胜I本人的本子号来形成,客户端在乞求的USportageI中标明要博取的财富的版本号。事实上,许多大企业如Instagram、Yammer、照片墙(TWT酷威.US)、谷歌(Google)等平时在他们的UEvoqueI里使用版本号。甚至像WSO二那样的API管理工科具也会在它的UGL450Ls中须要版本号。

  面向REST原则,版本管理技术快捷发展。因为它不包蕴HTTP规范中置放的header,也不扶助仅当二个新的能源或概念被引进时才应该添加新U猎豹CS陆I的见解——即版本不是表现情势的变更。另二人歌唱会对台戏的理由是能源ULANDI是不会随时间改变的,能源便是能源。

  UCR-VI应该能大致地分辨能源——而不是它的“形状”(状态)。另贰个便是必须钦命响应的格式(表征)。还有一对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”}

  未来,大家对相同能源请求版本二的数量:

  #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是怎么形成在区别的本子中分辨能源的。也许,若是客户端须求1个XML格式的数目,能够将Accept
header设置为”application/xml”,假如要求的话也得以带1个钦点的版本号。

  由于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”}

  恐怕,调用版本2的接口:

  #Request

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

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

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

  以后,版本管理通过UKoleosI本人的本子号来实现,客户端在乞请的ULANDI中标明要博得的能源的版本号。事实上,许多大公司如Twitter、Yammer、推文(Tweet)、谷歌等平时在他们的U奥迪Q3I里使用版本号。甚至像WSO贰那样的API管理工具也会在它的UEscortLs中必要版本号。

  面向REST原则,版本管理技术快捷发展。因为它不含有HTTP规范中置放的header,也不帮衬仅当一个新的能源或概念被引进时才应该添加新U帕杰罗I的理念——即版本不是表现方式的变更。另八个不予的理由是财富U福特ExplorerI是不会随时间改变的,能源就是财富。

  UCRUISERI应该能大致地辨识能源——而不是它的“形状”(状态)。另多个就是必须内定响应的格式(表征)。还有1部分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”}

  未来,我们对相同财富请求版本贰的数目:

  #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被用来表示所企盼的响应格式(以及示例中的版本号),注意上述五个一样的URAV4I是哪些实现在分裂的本子中分辨财富的。或然,要是客户端要求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格式的伸手,大概三种都支持,那么将由服务器来支配最后回到哪连串型的多少。但不论是服务器选拔哪一种,都会在响应中涵盖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”}

  恐怕,调用版本二的接口:

  #Request

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

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

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

  并不必要在每三个伸手中都钦赐版本号。由于HTTP
content-negotiation(内容协商)坚守类型的“最好匹配”格局,所以您的API也理应依照那一点。根据那壹标准化,当客户端从未点名版本时,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格式请求3个包括多版本能源的服务器,来创制3个新用户(预期会回来版本一):

  #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应当重返所支撑的最早版本。

  依旧这些例子,获取3个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格局向服务器发送数据时,如若服务器援助八个例外版本,而请求时又从未点名版本,和上边的例子1样——服务器会将小小/最早版本的多寡包涵在body中。为了拓展认证,上边的事例以JSON格式请求二个带有多版本财富的服务器,来创制3个新用户(预期会回来版本一):

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

请求不帮忙的版本

  当呼吁一个不援救的本子号时(包涵在API生命周期中早已熄灭的财富版本),API应当重回三个谬误的HTTP状态码40陆(表示不被接受)。其余,API还应该重返一个饱含Content-Type:
application/json的响应体,当中蕴藏2个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状态码40陆(表示不被接受)。其余,API还应当重临2个涵盖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”]

哪些时候应该创设1个新本子?

  API开发中的很多下边都会打破约定,并最后对客户端产生一些不良影响。如若您不明确API的修改会拉动怎么着的结果,保证起见最棒思考采纳版本控制。当您在设想提供三个新本子是还是不是安妥时,恐怕思量对现有的归来表征举办改动是不是必然能满意急需并被客户端所收受时,有这样多少个成分要思考。

哪些时候理应创建贰个新本子?

  API开发中的很多地点都会打破约定,并最后对客户端爆发部分不良影响。固然你不分明API的修改会推动什么样的结局,保障起见最佳思考采取版本控制。当你在设想提供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}”表明的意思是学员在越发时刻付诸试卷,而新的含义则是考察的约定完结时间。
  • 透过足够新的字段来改变现有的财富。将五个能源集合为1个并弃用原来的财富。
    • 有如此多少个财富”…/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}”表明的意义是学生在十一分时间付诸试卷,而新的含义则是侦查的预订实现时间。
  • 透过丰裕新的字段来改变现有的财富。将多少个能源统1为三个并弃用原来的财富。
    • 有诸如此类多少个财富”…/users/{id}/dropboxBaskets/{id}/messages/{id}”和”…/users/{id}/dropboxBaskets/{id}/messages/{id}/readStatus”。新需借使把readStatus财富的习性放到单独的message能源中,并弃用readStatus能源。那将促成messages能源中指向readStatus财富的链接被移除。

  即使上边列出的并不到家,但它交给了1部分会对客户端发生破坏性影响的更动类型,那时急需思索提供2个新能源或新本子。

非破坏性的改动

  • 在回来的JSON中添加新属性
  • 丰硕指向任何财富的”link”
  • 添加content-type援助的新格式
  • 添加content-language匡助的新格式
  • 鉴于API的创立人和买主都要拍卖不一致的casing,由此casing的变通非亲非故首要

非破坏性的改动

  • 在回去的JSON中添加新属性
  • 添加指向任何能源的”link”
  • 添加content-type帮助的新格式
  • 添加content-language帮衬的新格式
  • 是因为API的奠基人和消费者都要处理不一致的casing,因而casing的变通非亲非故首要

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

  建议对单个的财富实行版本控制。对API的1些转移,如修改工作流,可能要跨七个能源的版本控制,以此来幸免对客户端产生破坏性的影响。

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

  提出对单个的财富进行版本控制。对API的部分改观,如修改工作流,可能要跨七个能源的版本控制,以此来严防对客户端发生破坏性的影响。

运用Content-Location来提升响应

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

应用Content-Location来进步响应

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

带有Content-Type的链接

  Atom风格的链接协理”type”属性。提供丰裕的音讯以便客户端能够对特定的版本和内容类型举办调用。

带有Content-Type的链接

  Atom风格的链接扶助”type”属性。提供丰硕的新闻以便客户端能够对特定的版本和内容类型进行调用。

找出援助的本子

找出帮助的版本

笔者应该而且协理几个本子?

  维护四个区别的版本会让劳作变得繁琐、复杂、不难出错,而且代价高,对于别的给定的财富,你应该帮助不超越一个本子。

自个儿应该而且支持多少个版本?

  维护两个不等的版本会让工作变得繁琐、复杂、不难出错,而且代价高,对于别的给定的财富,你应该接济不抢先1个本子。

弃用

  Deprecated(弃用)的指标是用来证实能源对API还是可用,但在明日会不存在并变得不可用。留神:弃用的时间长度将由弃用政策决定——那里并不曾付诸定义。

弃用

  Deprecated(弃用)的目标是用来证实资源对API依旧可用,但在今日会不存在并变得不可用。瞩目:弃用的时间长度将由弃用政策决定——那里并未付诸定义。

本身怎么着告知客户端被弃用的能源?

  许多客户端未来拜会的能源大概在新本子引进后会被甩掉掉,由此,他们供给有一种格局来发现和督察他们的应用程序对弃用财富的使用。当呼吁2个弃用财富时,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”}

 

本身怎么样告知客户端被弃用的能源?

  许多客户端以后走访的财富大概在新本子引进后会被扬弃掉,因而,他们必要有一种办法来发现和监督他们的应用程序对弃用能源的行使。当呼吁三个弃用能源时,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中是以字符串的格式存在的,假若未钦赐统一的格式,那么解析日期也会是3个题材。

  在接口内部,服务端应该以UTC或达托霉素T时间来存款和储蓄、处理和缓存时间戳。这将实用化解日期和岁月的标题。

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

  有3个简约的方法能够化解这么些题材——在字符串中始终用平等的格式,蕴涵时间片(带有时区音讯)。ISO860一时间格式是八个科学的化解方案,它使用了完全增强的光阴格式,包罗小时、分钟、秒以及秒的小数部分(例如yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)。提出在REST服务的body内容中(请求和响应均包罗)使用ISO860一代表享有的日期格式。

  顺便提一下,对于那多少个基于JAVA的服务以来,DateAdapterJ库使用DateAdapter,Iso860一TimepointAdapter和HttpHeaderTimestampAdapter类可以分外不难地解析和格式化ISO8605日期和岁月,以及HTTP
1.1header(逍客FC11二3)格式。能够从https://github.com/tfredrich/DateAdapterJ下载。

  对于这么些创立基于浏览器的用户界面来说,ECMAScript五号正楷字经一起始就包括了JavaScript解析和创办ISO860二2日期的内容,所以它应该改成我们所说的主流浏览器所遵从的点子。当然,假设你要帮助那多少个不能够自动解析日期的旧版浏览器,能够应用JavaStript库或正则表明式。这里有多少个能够分析和创办ISO860一时间的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,Iso8601Timepoint艾达pter和HttpHeaderTimestampAdapter类能够非凡简单地剖析和格式化ISO8601二十三日期和时间,以及HTTP
一.一header(RubiconFC11二三)格式。能够从https://github.com/tfredrich/DateAdapterJ下载。

  对于那二个创立基于浏览器的用户界面来说,ECMAScript五标准壹早先就隐含了JavaScript解析和制造ISO860八日期的情节,所以它应有成为大家所说的主流浏览器所遵从的艺术。当然,要是您要帮助那个无法自动解析日期的旧版浏览器,可以采用JavaStript库或正则表达式。那里有多少个能够分析和开创ISO860壹时间的JavaStript库:

  http://momentjs.com/

  http://www.datejs.com/

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

  但是上述建议仅适用于HTTP请求或响应内容中的JSON和XML内容,HTTP规范针对HTTP
headers使用另壹种差别的格式。在被LacrosseFC11贰三更替的CR-VFC82第22中学建议,该格式包含了各类日期、时间和date-time格式。不过,提出始终使用时间戳格式,在您的request
headers中它看起来像那样:

  Sun, 06 Nov 1994 08:49:37 GMT

  可是,那种格式没有设想皮秒只怕秒的10进制小数。Java的SimpleDataFormat的格式串是:”EEE,
dd MMM yyyy HH:mm:ss ‘威他霉素T'”。

 

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

  然则上述提出仅适用于HTTP请求或响应内容中的JSON和XML内容,HTTP规范针对HTTP
headers使用另1种差别的格式。在被XC60FC11贰3更替的OdysseyFC822中提议,该格式包罗了种种日期、时间和date-time格式。但是,提议始终使用时间戳格式,在你的request
headers中它看起来像这么:

  Sun, 06 Nov 1994 08:49:37 GMT

  不过,那种格式未有思念微秒或许秒的10进制小数。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. 1旦授权通过了,服务器将会继续健康运营。

  上边第1步的花费也许会相比大,可是即使假诺存在1个可缓存的权力决定列表(ACL),那么在产生远程请求前,能够在地头创制一个授权客户端来缓存最新的ACLs。

护卫服务的海东

  Authentication(身份声明)指的是确认给定的央浼是从服务已知的某人(或有些系统)发出的,且请求者是她协调所证明的特别人。Authentication是为了证实请求者的实在身份,而authorization(授权)是为着验证请求者有权力去执行被呼吁的操作。

  本质上,那么些进度是那样的:

  1. 客户端发起三个请求,将authentication的token(身份注明确命令牌)包括在X-Authentication
    header中,或者将token叠加在央求的查询串参数中。
  2. 服务器对authorization
    token(授权令牌)举办检查,并开始展览求证(有效且未过期),并依据令牌内容分析大概加载认证中心。
  3. 服务器调用授权服务,提供注脚宗旨、被呼吁能源和必备的操作许可。
  4. 设若授权通过了,服务器将会再三再四健康运维。

  下边第贰步的开支或许会相比较大,不过要是假诺存在四个可缓存的权杖决定列表(ACL),那么在发生远程请求前,可以在地面创设二个授权客户端来缓存最新的ACLs。

身份验证

  最近最佳的做法是行使OAuth身份验证。强烈推荐OAuth二,可是它仍旧处于草案情形。大概选取OAuth一,它完全能够胜任。在好几情状下也足以选拔叁-Legged
OAuth。越来越多关于OAuth的行业内部可以查阅那里http://oauth.net/documentation/spec/

  OpenID是一个增选举择。但是建议将OpenID作为一个外加的身份验证选项,以OAuth为主。越多关于OpenID的标准能够查阅那里http://openid.net/developers/specs/

身份验证

  方今最棒的做法是接纳OAuth身份验证。强烈推荐OAuth二,可是它依旧处于草案情形。大概采用OAuth壹,它完全可以胜任。在好几景况下也足以选取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。OAuth二要求授权服务器和access
token(访问令牌)来行使TLS(安全传输层协议)。

  在HTTP和HTTPS之间切换会带来安全隐患,最好的做法是颇具简报私下认可都应用TLS。

授权

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

授权

  对服务的授权和对其他应用程序的授权一样,未有别的分裂。它依照那样1个题材:“主体是还是不是对给定的资源有请求的许可?”那里给出了简短的3项数据(主体,能源和批准),因而很简单构造三个帮衬那种概念的授权服务。个中重点是被授予财富访问许可的人或系统。使用那个相似概念,就足以为每三个主旨创设2个缓存访问控制列表(ALC)。

应用程序安全

  对RESTful服务来说,开发多少个平安的web应用适用同样的标准化。

  • 在服务器上印证全数输入。接受“已知”的正确的输入并驳回错误的输入。
  • 防止SQL和NoSQL注入。
  • 使用library如微软的Anti-XSS或OWASP的AntiSammy来对出口的多少开始展览编码。
  • 将新闻的长短限制在规定的字段长度内。
  • 劳务应该只显示1般的错误新闻。
  • 牵挂工作逻辑攻击。例如,攻击者能够跳过多步骤的预购流程来预定产品而无需输入信用卡新闻吗?
  • 对疑惑的运动记录日志。

  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的AntiSammy来对输出的数量实行编码。
  • 将消息的尺寸限制在鲜明的字段长度内。
  • 服务应该只显示壹般的错误音信。
  • 设想工作逻辑攻击。例如,攻击者能够跳过多步骤的订货流程来预约产品而无需输入信用卡音信呢?
  • 对疑忌的移动记录日志。

  RESTful安全必要专注的地点:

  • 证实数据的JSON和XML格式。
  • HTTP动词应该被限定在允许的艺术中。例如,GET请求不能够去除1个实体。GET用来读取实体而DELETE用来删除实体。
  • 专注race
    conditions(竞争原则——由于五个可能多个经过竞争使用不可能被同时做客的财富,使得这几个进程有一点都不小只怕因为日子上推进的次第原由此出现难题)。

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

  • 蹲点API的应用境况,并领悟如何活动是不奇怪的,哪些是非常常的。
  • 限定API的行使,使恶意用户不可能停掉二个API服务(DOS攻击),并且有力量阻止恶意的IP地址。
  • 将API密钥存款和储蓄在加密的安全密钥库中。

 

缓存和可伸缩性

  通过在系统层级解决通过远程调用来博取请求的多寡,缓存进步了系统的可扩张性。服务通过在响应中装置headers来增加缓存的能力。遗憾的是,HTTP
壹.0中与缓存相关的headers与HTTP
1.一不一,因而服务器要同时帮忙三种版本。下表给出了GET请求要协理缓存所必须的最少headers集合,并交给了极度的叙说。

HTTP Header

描述

示例

Date

响应再次来到的日期和岁月(中华VFC11二叁格式)。

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

Cache-Control

一呼百应可被缓存的最大秒数(最大age值)。若是响应不支持缓存,值为no-cache。

Cache-Control: 360

Cache-Control: no-cache

Expires

假使给出了最大age值,该时间戳(中华VFC11二3格式)表示的是响应过期的年华,也正是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

财富本人最后被改动的时光戳(SportageFC1123格式)。

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

  为了简化,那里举3个响应中的headers集合的事例。那是三个简约的对财富开始展览GET请求的响应,缓存时间长度为1天(二4小时):

  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
一.0中与缓存相关的headers与HTTP
一.一分化,由此服务器要同时辅助三种版本。下表给出了GET请求要扶助缓存所不可不的最少headers集合,并交给了得当的叙述。

HTTP Header

描述

示例

Date

一呼百应重回的日子和时间(RAV四FC112叁格式)。

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

Cache-Control

壹呼百应可被缓存的最大秒数(最大age值)。如若响应不支持缓存,值为no-cache。

Cache-Control: 360

Cache-Control: no-cache

Expires

借使给出了最大age值,该时间戳(PRADOFC11二3格式)表示的是响应过期的岁月,约等于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

财富本人最终被修改的年月戳(KoleosFC11二三格式)。

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

  为了简化,那里举叁个响应中的headers集合的例证。这是1个简练的对能源实行GET请求的响应,缓存时间长度为一天(二4钟头):

  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

  下边是1个近似的例子,但是缓存被统统禁用:

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

ETag Header

  ETag
header对于表明缓存数据的新旧程度很有用,同时也推进条件的读取和翻新操作(分别为GET和PUT)。它的值是两个任意字符串,用来代表回到数据的本子。可是,对于再次回到数据的例外格式,它也得以不相同——JSON格式响应的ETag与同壹能源XML格式响应的ETag会不相同。ETag
header的值能够录像带有格式的底层域对象的哈希表(例如Java中的Obeject.hashcode())1样不难。提出为各类GET(读)操作重返2个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状态码不太平日应用,它们照旧更与众区别,要么更加高级。抢先10分之伍劳务套件只帮忙那个常用的状态码,甚至只扶助当中的壹部分,并且它们都能平常干活。

  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)
—— 当服务器抛出越发时,捕捉到的1般错误。

 

HTTP状态码(前10)

  以下是由RESTful服务或API再次回到的最常用的HTTP状态码,以及一些有关它们普遍用法的总结表明。其余HTTP状态码不太平时利用,它们也许更奇特,要么越来越尖端。大多数劳动套件只援救那几个常用的状态码,甚至只援助当中的一有些,并且它们都能健康干活。

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

  201 (CREATED) ——(通过POST或PUT)创设成功。通过设置Location
header来含有3个针对性最新成立的能源的链接。

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

  304 (NOT MODIFIED)
—— 用于有标准化的GET调用的响应,以调整和收缩带宽的使用。
假使使用该景况,那么必须为GET调用设置Date、Content-Location和ETag
headers。不含有响应体。

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

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

  403 (FORBIDDEN)
—— 未授权的用户执行操作,未有权限访问财富,只怕出于1些原因能源不可用(如时间范围等),使用该错误码。

  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

相关文章