据他们说能源,基于财富

正文主要读者

正文首要读者

引言

引言

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更像是一种规格的会晤。除了八个重点的规13分就向来不别的的正统了。实际上,纵然有所谓的“最佳实践”和正规,但那几个东西都和宗派斗争一样,在频频地演化。

  本文围绕REST的广阔难点建议了见识和仿食谱式的议论,并经过介绍一些归纳的背景知识对创制真实情状下的预生产条件中千篇一律的REST服务提供文化。本文收集了来自别的渠道的音讯,经历过3回次的败诉后不断创新。

  但对此REST方式是或不是肯定比SOAP好用仍有较大争议(反之亦然),或许在一些情形下仍亟需成立SOAP服务。本文在提及SOAP时并未花较大篇幅来谈谈它的相对优点。相反由于技术和行业在不断升高,大家将继续绳锯木断我们的比方–REST是及时统一筹划web服务的特等情势。

  第3片段概述REST的含义、设计准则和它的出格之处。第③部分罗列了有些小贴士来回想REST的劳务理念。之后的有些则会更尖锐地为web服务创制人士提供部分细节的支撑和研讨,来促成一个可见公开始展览示在生养环境中的高质量REST服务。

 

引言

  于今已有多量有关RESTful
Web服务至上实践的连锁材质(详见本文最后的相关文献部分)。由于撰文的光阴不一,许多材质中的内容是顶牛的。其余,想要通过翻看文献来打探这种服务的提升是不太可取的。为了打探RESTful这一定义,至少需求查阅三到五本有关文献,而本文将能够帮你加速这一进度——扬弃多余的探究,最大化地提炼出REST的特级实践和规范。

  与其说REST是一套标准,REST更像是一种规格的聚众。除了多少个相当重要的规范外就平昔不其余的正规化了。实际上,就算有所谓的“最佳实践”和正式,但这个东西都和宗派斗争一样,在频频地衍生和变化。

  本文围绕REST的常见难题建议了见识和仿食谱式的议论,并经过介绍一些简练的背景知识对创制真实景况下的预生产条件中同样的REST服务提供文化。本文收集了来自别的渠道的新闻,经历过三遍次的挫败后不断创新。

  但对此REST方式是或不是必然比SOAP好用仍有较大争议(反之亦然),大概在一些景况下仍亟需创立SOAP服务。本文在提及SOAP时并未花较大篇幅来谈谈它的相持优点。相反由于技术和行业在不断升高,大家将继承坚持大家的若是–REST是即时统一筹划web服务的特级艺术。

  第2部分概述REST的意义、设计准则和它的万分之处。第1有的罗列了有的小贴士来纪念REST的服务理念。之后的局地则会更尖锐地为web服务成立人士提供部分细节的支撑和钻探,来实现三个力所能及掌握映今后生养环境中的高质量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架构
  • 分层系统
  • 按需编码

  以下是那些规划准则的事无巨细研究:

统一接口

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

集合接口

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

  基于能源

  不一样能源要求用U帕JeroI来唯一标识。重返给客户端的表征和能源本人在概念上有所不相同,例如服务端不会直接传送2个数据库财富,可是,一些HTML、XML或JSON数据可见展现部分数据库记录,如用立陶宛语来表明照旧用UTF-8编码则要根据请求和服务器完毕的细节来控制。

  基于财富

  不一样能源要求用USportageI来唯一标识。重回给客户端的特征和能源自身在概念上有所分裂,例如服务端不会直接传送贰个数据库财富,可是,一些HTML、XML或JSON数据可见显示部分数据库记录,如用克罗地亚语来抒发依然用UTF-8编码则要基于请求和服务器达成的细节来支配。

  通过特色来操作财富

  当客户端收到包涵元数据的能源的特征时,在有权力的情景下,客户端已控制的十足的新闻,能够对服务端的财富拓展删改。

  通过特色来操作财富

  当客户端收到包蕴元数据的能源的特色时,在有权力的事态下,客户端已控制的足足的新闻,能够对服务端的财富拓展删改。

  自描述的音讯

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

  自描述的新闻

  每条新闻都蕴含丰富的数额用于确认音信该如何处理。例如要由网络媒体类型(已知的如MIME类型)来确认需调用哪个解析器。响应同样也评释了它们的缓存能力。

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

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

  除了上述情节外,HATEOS也象征,须求的时候链接也可被含有在回到的body(或底部)中,以提供ULX570I来探寻对象自作者或涉及对象。下文将对此展开更详实的演说。

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

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

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

  除了上述剧情外,HATEOS也代表,须要的时候链接也可被含有在回来的body(或尾部)中,以提供ULacrosseI来搜寻对象自作者或涉嫌对象。下文将对此开展更详尽的论述。

  统一接口是各样REST服务安排时的须要准则。

无状态

  正如REST是REpresentational State
Transfer的缩写,无状态很重要。本质上,那评释了处理请求所需的情状已经包含在恳求小编里,也有大概是URI的一有的、查询串参数、body或尾部。U凯雷德I可以唯一标识每种资源,body中也暗含了财富的转态(或转态变更意况)。之后,服务器将开始展览处理,将相关的状态或能源通过底部、状态和响应body传递给客户端。

  从事大家这一行业的绝大多数人都习惯使用容器来编程,容器中有一个“会话”的概念,用于在四个HTTP请求下保持状态。在REST中,如果要在七个请求下维持用户情状,客户端必须回顾客户端的具备音讯来成功请求,要求时再度发送请求。自从服务端不供给保持、更新或传递会话状态后,无状态性获得了更大的延展。其余,负载均衡器无需担心和无状态系统里面的对话。

  所以状态和财富间有啥差距?服务器对于状态,恐怕说是应用状态,所关怀的点是在此时此刻对话或请求中要做到请求所需的多少。而财富,或者说是能源情形,则是概念了能源特色的数量,例如存款和储蓄在数据库中的数据。总而言之,应用状态是是随着客户端和伸手的改动而变更的数码。相反,能源气象对于发出请求的客户端的话是不变的。

  在互联网采纳的某一一定岗位上摆放一个回去按钮,是因为它仰望你能按一定的次第来操作吗?其实是因为它违反了无状态的准绳。有无数不恪守无状态原则的案例,例如3-Legged
OAuth,API调用速度限制等。但还是要尽量确定保证服务器中不需求在多少个请求下保持利用状态。

无状态

  正如REST是REpresentational State
Transfer的缩写,无状态很要紧。本质上,那证明了处理请求所需的景况已经包括在伸手作者里,也有恐怕是U奥迪Q3I的一片段、查询串参数、body或尾部。UGL450I能够唯一标识每一种财富,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请求不可能更改任何秘密的财富数量。衡量和跟踪仍恐怕发生,但只会更新数据而不会更新由ULANDI标识的能源数量。

客观的能源名

  合理的财富名称恐怕路径(如/posts/23而不是/api?type=posts&id=23)可以更精通1个呼吁的目标。使用ULANDL查询串来过滤数据是很好的法门,但不应有用于固定能源名称。

  适当的能源名称为服务端请求提供上下文,扩展服务端API的可精通性。通过U奇骏I名称分层地查看资源,能够给使用者提供2个团结的、不难掌握的能源层次,以在他们的应用程序上接纳。资源名称应当是名词,防止为动词。使用HTTP方法来钦点请求的动作部分,能让事情更是的原原本本。

理所当然的能源名

  合理的资源名称或然路径(如/posts/23而不是/api?type=posts&id=23)能够更显眼贰个请求的指标。使用UCR-VL查询串来过滤数据是很好的不二法门,但不应当用于固定财富名称。

  适当的财富名称为服务端请求提供上下文,扩大服务端API的可精通性。通过UCRUISERI名称分层地查看能源,能够给使用者提供一个团结的、简单领悟的能源层次,以在他们的应用程序上利用。财富名称应当是名词,幸免为动词。使用HTTP方法来内定请求的动作部分,能让事情更是的鲜明。

XML和JSON

  建议默许援助json,并且,除非开销很震惊,不然就同时援救json和xml。在优质状态下,让使用者仅通过变更扩张名.xml和.json来切换类型。其它,对于援救ajax风格的用户界面,2个棉被服装进的响应是十三分有救助的。提供一个被包裹的响应,在暗中认可的照旧有单独增添名的景色下,例如:.wjson和.wxml,讲明客户端请求3个棉被服装进的json或xml响应(请参见上边包车型客车包装响应)。

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

  关于REST服务中xml的施用,xml的标准和预定除了利用语法正确的竹签和文本外没有其余的法力。尤其地,命名空间不是也不应该是被运用在REST服务端的左右文中。xml的回到更接近于json——不难、简单阅读,没有情势和命名空间的细节展现——仅仅是数量和链接。固然它比那更复杂的话,参看本节的首先段——使用xml的资金是惊心动魄的。鉴于大家的经验,很少有人利用xml作为响应。在它被统统淘汰以前,那是最终三个可被肯定的地点。

XML和JSON

  建议暗中同意帮衬json,并且,除非开支很惊人,不然就同时支持json和xml。在地道图景下,让使用者仅通过改变扩充名.xml和.json来切换类型。其余,对于支撑ajax风格的用户界面,四个被卷入的响应是13分有帮忙的。提供二个棉被服装进的响应,在暗许的依然有单独扩大名的状态下,例如:.wjson和.wxml,阐明客户端请求3个被卷入的json或xml响应(请参见上面的包装响应)。

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

  关于REST服务中xml的运用,xml的科班和预定除了使用语法正确的标签和文本外没有任何的功力。尤其地,命名空间不是也不应有是被利用在REST服务端的上下文中。xml的归来更接近于json——简单、简单阅读,没有情势和命名空间的底细显示——仅仅是数据和链接。假若它比那更扑朔迷离的话,参看本节的第1段——使用xml的老本是惊心动魄的。鉴于大家的经验,很少有人利用xml作为响应。在它被全然淘汰以前,那是终极1个可被肯定的地点。

创办适当粒度的财富

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

创办适当粒度的能源

  一伊始,系统中模拟底层应用程序域或数据库架构的API更易于被创建。最后,你会期待将这个服务都构成到一道——利用多项底层财富减少通讯量。在创制独立的能源之后更创造更大粒度的能源,比从更大的合集中创造较大粒度的能源越来越便于一些。从局地小的简单定义的能源开头,创立CRUD(增加和删除查改)成效,可以使财富的开创变得更易于。随后,你能够成立那一个依照用例和削减通讯量的能源。

设想连通性

  REST的规律之一就是连通性——通过超媒体链接达成。当在响应中回到链接时,api变的更具有自描述性,而在一向不它们时服务端依旧可用。至少,接口自己能够为客户端提供哪些寻找数据的参考。别的,在经过POST方法创造财富时,还是能够运用头地点包括一个链接。对于响应中援救分页的集聚,”first”、
“last”、”next”、和”prev”链接至少是卓殊有效的。

 

考虑连通性

  REST的原理之一正是连通性——通过超媒体链接达成。当在响应中回到链接时,api变的更兼具自描述性,而在向来不它们时服务端依旧可用。至少,接口本人能够为客户端提供哪些寻找数据的参照。别的,在经过POST方法创造财富时,还足以选择头地点包罗三个链接。对于响应中帮忙分页的相会,”first”、
“last”、”next”、和”prev”链接至少是万分有效的。

 

定义

定义

幂等性

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

在微型总计机科学中,术语幂等用于更全面地讲述贰个操作,一遍或频仍执行该操作爆发的结果是如出一辙的。依据使用的上下文,那说不定有不一致的意义。例如,在点子照旧子例程调用全部副效用的情形下,意味着在第①调用之后被修改的意况也保持不变。

  从REST服务端的角度来看,由于操作(或服务端调用)是幂等的,客户端能够用重新的调用而发出相同的结果——在编制程序语言中操作像是一个”setter”(设置)方法。换句话说,正是应用七个一律的乞求与应用单个请求效果同样。注意,当幂等操作在服务器上产生同样的结果(副作用),响应自个儿可能是例外的(例如在八个请求之间,财富的境况大概会变动)。

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

幂等性

  不要从字面意思来明白什么是幂等性,恰恰相反,那与一些职能紊乱的世界非亲非故。上边是缘于维基百科的解释:

在电脑科学中,术语幂等用于更宏观地描述3个操作,一回或频仍执行该操作爆发的结果是一律的。依据使用的上下文,那说不定有例外的含义。例如,在艺术可能子例程调用具有副作用的气象下,意味着在率先调用之后被涂改的景观也保险不变。

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

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

安全

  来自维基百科:

部分措施(例如GET、HEAD、OPTIONS和TRACE)被定义为安全的主意,那意味着它们仅被用来音信寻找,而无法改变服务器的气象。换句话说,它们不会有副功能,除了相对来说无毒的震慑如日志、缓存、横幅广告或计数服务等。任意的GET请求,不考虑使用状态的上下文,都被认为是高枕无忧的。

  同理可得,安全意味着调用的章程不会挑起副成效。由此,客户端可以屡屡使用安全的伸手而不用担心对服务端爆发其余副成效。那表示服务端必须服从GET、HEAD、OPTIONS和TRACE操作的乌兰察布概念。不然,除了对消费端产生模糊外,它还会造成Web缓存,搜索引擎以及任何活动代理的难题——这将在服务器上发生出人意料的结果。

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

  安全的点子被实现为只读操作。不过,安全并不意味服务器必须每一趟都回到相同的响应。

 

安全

  来自维基百科:

有些方式(例如GET、HEAD、OPTIONS和TRACE)被定义为安全的主意,那代表它们仅被用来信息寻找,而无法改变服务器的景色。换句话说,它们不会有副功能,除了相对来说无毒的熏陶如日志、缓存、横幅广告或计数服务等。任意的GET请求,不考虑采纳状态的上下文,都被认为是安全的。

  由此可见,安全意味着调用的方法不会滋生副成效。由此,客户端能够频仍使用安全的请求而不用担心对服务端发生任何副作用。那表示服务端必须服从GET、HEAD、OPTIONS和TRACE操作的平安概念。不然,除了对消费端产生模糊外,它还会促成Web缓存,搜索引擎以及其它活动代理的题材——那将在服务器上爆发意料之外的后果。

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

  安全的措施被完成为只读操作。然则,安全并不意味服务器必须每趟都回去相同的响应。

 

HTTP动词

  Http动词主要遵从“统一接口”规则,并提须要我们相应的依照名词的财富的动作。最关键如故最常用的http动词(只怕叫做方法,那样称呼只怕更安妥些)有POST、GET、PUT和DELETE。那些分别对应于成立、读取、更新和删除(CRUD)操作。也有众多别样的动词,不过利用作用相比低。在这几个使用较少的点子中,OPTIONS和HEAD往往利用得更加多。

HTTP动词

  Http动词首要遵守“统一接口”规则,并提供给我们相应的基于名词的财富的动作。最要紧依然最常用的http动词(恐怕叫做方法,那样称呼恐怕更妥当些)有POST、GET、PUT和DELETE。这一个分别对应于创立、读取、更新和删除(CRUD)操作。也有不少别的的动词,可是利用成效相比较低。在这一个使用较少的格局中,OPTIONS和HEAD往往选择得越来越多。

GET

  HTTP的GET方法用于检索(或读取)财富的数目。在不利的乞请路径下,GET方法会再次来到3个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)请求仅用于读取数据而不改变多少。因而,那种应用办法被认为是平安的。相当于说,它们的调用没有数据修改或污染的高风险——调用一遍和调用13回照旧尚未被调用的功效同样。别的,GET(以及HEAD)是幂等的,那表示使用多个一样的央浼与利用单个的央浼最终都享有同样的结果。

  不要通过GET揭发不安全的操作——它应有永远都无法改改服务器上的别样资源。

GET

  HTTP的GET方法用于检索(或读取)能源的数码。在不利的呼吁路径下,GET方法会重临二个xml只怕json格式的多少,以及1个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)请求仅用于读取数据而不改动多少。因而,这种应用格局被认为是高枕无忧的。也正是说,它们的调用没有数量修改或污染的风险——调用三次和调用13回还是尚未被调用的功能等同。其它,GET(以及HEAD)是幂等的,那象征使用八个一样的伏乞与利用单个的呼吁最后都怀有相同的结果。

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

PUT

  PUT经常被用于立异能源。通过PUT请求2个已知的能源URAV4I时,须求在呼吁的body中涵盖对原有能源的换代数据。

  可是,在财富ID是由客服端而非服务端提供的场合下,PUT同样能够被用来创造能源。换句话说,假诺PUT请求的U索罗德I中隐含的财富ID值在服务器上不设有,则用于创立能源。同时呼吁的body中务必含有要创设的财富的数据。有人认为那会生出歧义,所以唯有真的须要,使用那种情势来成立资源应该被慎用。

  或许大家也得以在body中提供由客户端定义的财富ID然后使用POST来创造新的能源——固然请求的U福特ExplorerI中不带有要开创的能源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请求叁个已知的财富UEscortI时,要求在央浼的body中涵盖对原有财富的换代数据。

  可是,在资源ID是由客服端而非服务端提供的状态下,PUT同样能够被用来创立财富。换句话说,若是PUT请求的U途乐I中包涵的能源ID值在服务器上不设有,则用来创设财富。同时请求的body中必须蕴涵要创立的能源的多少。有人以为这会发生歧义,所以唯有真的要求,使用那种措施来创制能源应该被慎用。

  大概大家也得以在body中提供由客户端定义的能源ID然后使用POST来成立新的财富——若是请求的USportageI中不含有要开创的财富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不是1个安全的操作,因为它会修改(或成立)服务器上的景况,但它是幂等的。换句话说,倘使你使用PUT创造恐怕更新能源,然后再一次调用,财富依旧存在并且状态不会发生变化。

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

POST

  POST请求平时被用来创制新的能源,尤其是被用来创立从属能源。从属能源即归属于其余财富(如父财富)的能源。换句话说,当创设2个新能源时,POST请求发送给父能源,服务端负责将新财富与父能源开始展览关联,并分配贰个ID(新能源的U本田UR-VI),等等。

  例如:

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

  当创造成功时,重临HTTP状态码201,并顺便一个地方头消息,在那之中蕴藏指向初阶创制的能源的链接。

  POST请求既不是高枕无忧的又不是幂等的,由此它被定义为非幂等性财富请求。使用多个一律的POST请求很可能会造成创建五个带有相同新闻的财富。

POST

  POST请求常常被用于成立新的资源,尤其是被用来创设从属能源。从属能源即归属于其它财富(如父能源)的能源。换句话说,当创造两个新财富时,POST请求发送给父能源,服务端负责将新能源与父财富拓展关联,并分配一个ID(新能源的UKoleosI),等等。

  例如:

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

  当成立成功时,重回HTTP状态码201,并顺便一个地点头消息,其中含有指向开首创造的财富的链接。

  POST请求既不是安全的又不是幂等的,由此它被定义为非幂等性财富请求。使用多少个相同的POST请求很只怕会导致创制七个饱含相同新闻的能源。

PUT和POST的创办相比

  可想而知,大家提出利用POST来创造能源。当由客户端来控制新能源具有怎么样U福睿斯I(通过财富名称或ID)时,使用PUT:即只要客户端知道UPRADOI(或财富ID)是何许,则对该U奥迪Q5I使用PUT请求。否则,当由服务器或服务端来决定创制的财富的U奥德赛I时则动用POST请求。换句话说,当客户端在开创此前不明了(或不大概知晓)结果的U昂CoraI时,使用POST请求来创设新的能源。

PUT和POST的创始相比

  总而言之,大家建议选择POST来创制能源。当由客户端来支配新财富有着哪些U帕杰罗I(通过资源名称或ID)时,使用PUT:即只要客户端知道U卡宴I(或能源ID)是怎么样,则对该UCRUISERI使用PUT请求。否则,当由服务器或服务端来控制创办的财富的U帕杰罗I时则使用POST请求。换句话说,当客户端在创造之前不亮堂(或不可能领会)结果的U奥迪Q5I时,使用POST请求来创建新的能源。

DELETE

  DELETE很简单精通。它被用来依照U途锐I标识删除财富。

  例如:

  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状态码204(表示无内容)表示尚无响应体。由此可见,能够回去状态码204意味着一向不响应体,只怕再次回到状态码200并且附带JSON风格的响应体。

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

  然则,那里有一个有关DELETE幂等性的警告。在一个能源上第①遍调用DELETE往往会回去404(未找到),因为该能源已经被移除了,所以找不到了。那使得DELETE操作不再是幂等的。若是能源是从数据库中去除而不是被回顾地方统一标准记为除去,那种场馆要求适当让步。

  下表计算出了严重性HTTP的主意和能源U凯雷德I,以及推荐的重临值:

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很不难通晓。它被用来依据U奥迪Q3I标识删除财富。

  例如:

  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状态码204(表示无内容)表示从未响应体。同理可得,能够回到状态码204表示尚未响应体,大概再次来到状态码200同时附带JSON风格的响应体。

  根据HTTP规范,DELETE操作是幂等的。假如您对叁个财富进行DELETE操作,财富就被移除了。在能源上屡次调用DELETE最后造成的结果都一律:即能源被移除了。但如若将DELETE的操作用于计数器(财富内部),则DETELE将不再是幂等的。如前方所述,只要数据尚未被更新,计算和度量的用法还是可被认为是幂等的。建议非幂等性的能源请求使用POST操作。

  然则,那里有3个关于DELETE幂等性的警告。在3个能源上第一遍调用DELETE往往会回来404(未找到),因为该能源已经被移除了,所以找不到了。那使得DELETE操作不再是幂等的。假诺财富是从数据库中删除而不是被总结地方统一标准记为除去,那种境况必要适宜让步。

  下表总计出了重庆大学HTTP的章程和财富U奔驰M级I,以及引进的重回值:

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动词,在开创叁个能够精通的、易于使用的Web服务API时,能源命名能够说是最具有争议和最关键的定义。一个好的能源命名,它所对应的API看起来更直观并且易于使用。相反,假职责名倒霉,同样的API会令人感到很工巧并且难以通晓和选取。当您要求为您的新API创设能源U奥德赛L时,那里有部分小技巧值得借鉴。

  从实质上讲,叁个RESTFul
API最后都得以被回顾地作为是一堆U宝马X5I的聚众,HTTP调用那么些UEvoqueI以及部分用JSON和(或)XML表示的能源,它们中有众多饱含了相互关系的链接。RESTful的可寻址能力主要借助UPRADOI。每一个财富都有和好的地方或UWranglerI——服务器能提供的每四个使得的新闻都得以看作能源来公开。统一接口的尺码部分地通过U福睿斯I和HTTP动词的结合来化解,并符合利用专业和预订。

  在支配你系统中要运用的能源时,使用名词来命名这几个能源,而不是用动词或动作来定名。换句话说,叁个RESTful
USportageI应该提到到3个实际的能源,而不是关联到1个动作。其它,名词还装有部分动词没有的属性,这也是另八个强烈的要素。

  一些能源的例子:

  • 系统的用户
  • 学生注册的科目
  • 三个用户帖子的小运轴
  • 关爱其余用户的用户
  • 一篇关于骑马的稿子

  服务套件中的种种能源最少有二个U奇骏I来标识。假诺那一个USportageI能表示必定的意义并且能够充裕描述它所代表的财富,那么它正是一个最好的命名。U汉兰达I应该负有可预测性和分支结构,那将有助于增高它们的可驾驭性和可用性的:可预测指的是财富应该和称号保持一致;而分层指的是数量具有关系上的构造。那并非REST规则或正式,不过它加重了对API的定义。

  RESTful
API是提供给消费端的。U纳瓦拉I的称呼和协会应该将它所发挥的含义传达给消费者。平日大家很难理解数码的境界是怎么,不过从您的多寡上您应有很有可能去尝试找到要回到给客户端的数量是何等。API是为客户端而规划的,而不是为你的数目。

  假使我们未来要讲述一个席卷客户、订单,列表项,产品等效果的订单系统。考虑一下大家该怎么来叙述在那个服务中所涉及到的能源的ULANDIs:

资源命名

  除了适当地利用HTTP动词,在开立二个方可见晓的、易于使用的Web服务API时,财富命名能够说是最具有争议和最根本的概念。3个好的能源命名,它所对应的API看起来更直观并且易于使用。相反,假设命名不好,同样的API会令人感觉到很愚昧并且难以驾驭和应用。当您供给为你的新API创建财富U福特ExplorerL时,那里有一对小技巧值得借鉴。

  从精神上讲,三个RESTFul
API最后都得以被略去地看成是一堆U奇骏I的集合,HTTP调用这么些U本田CR-VI以及部分用JSON和(或)XML表示的能源,它们中有广大涵盖了互相关联的链接。RESTful的可寻址能力根本依靠USportageI。种种财富都有友好的地址或UTiggoI——服务器能提供的每3个灵光的音讯都足以看成能源来公开。统一接口的尺度部分地经过U凯雷德I和HTTP动词的结缘来化解,并符合利用规范和约定。

  在支配你系统中要动用的财富时,使用名词来定名那些财富,而不是用动词或动作来命名。换句话说,3个RESTful
UMuranoI应该提到到贰个现实的能源,而不是关系到四个动作。此外,名词还享有局地动词没有的属性,那也是另二个显眼的成分。

  一些财富的事例:

  • 系统的用户
  • 学员注册的科目
  • 贰个用户帖子的年华轴
  • 关注别的用户的用户
  • 一篇有关骑马的稿子

  服务套件中的每一种能源最少有二个U福特ExplorerI来标识。假如这么些UOdysseyI能表示肯定的意思并且能够尽量描述它所代表的财富,那么它正是八个最好的命名。U奇骏I应该具有可预测性和分支结构,那将促进增强它们的可精通性和可用性的:可预测指的是资源应该和称号保持一致;而分层指的是多少有所关系上的布局。这并非REST规则或专业,可是它加重了对API的概念。

  RESTful
API是提要求消费端的。UENCOREI的名号和结构应当将它所公布的意思传达给买主。经常大家很难知晓数据的境界是如何,可是从你的多寡上您应当很有恐怕去品味找到要回到给客户端的数量是什么样。API是为客户端而陈设的,而不是为您的数码。

  借使大家前几天要描述3个席卷客户、订单,列表项,产品等效果的订单系统。考虑一下大家该怎么来叙述在这么些服务中所涉及到的能源的U瑞鹰Is:

资源URI示例

  为了在系统中插入(创设)一个新的用户,大家得以选拔:

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

 

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

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

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

 

  下边是对产品有关的U景逸SUVI的有些提议:

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

  用于创设新的制品。

 

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

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

 

  那么,怎么着为用户创造2个新的订单呢?

  一种方案是:

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

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

  

  因为大家想为用户创制贰个订单(注意之间的关联),那些URubiconI可能不够直观,下边那个U途锐I则更清楚一些:

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

  现在我们掌握它是为编号33245的用户成立3个订单。

 

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

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

  或者是1个号码为33245的用户所制造或享有的订单列表。注意:大家能够遮挡对该UMuranoI进行DELETE或PUT请求,因为它的操作对象是二个凑合。

 

  继续深远,那上边这几个U安德拉I的请求又象征如何吧?

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

  大概是(为编号33245的用户)扩展贰个数码为8769的订单条目。没错!假诺利用GET情势呼吁那个U中华VI,则会再次来到这一个订单的有着条条框框。可是,尽管这个条款与用户消息无关,大家将会提供POST
www.example.com/orders/8769/lineitems
这个URI。

  从再次来到的这个条款来看,钦赐的财富或然会有多少个U奥迪Q3Is,所以我们或然也亟需求提供那样3个U奥迪Q5I
GET
http://www.example.com/orders/8769
,用来在不亮堂用户ID的状态下基于订单ID来询问订单。

 

  更进一步:

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

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

  今后您应当驾驭什么是分层组织了。它们并不是严厉的规则,只是为了有限帮助在您的服务中那么些强制的组织能够更便于被用户所驾驭。与拥有软件开发中的技能一样,命名是打响的首要性。

  

  多看有个别API的言传身教并学会控制那些技巧,和你的队友一起来周密你API能源的U凯雷德Is。这里有一部分APIs的例子:

资源URI示例

  为了在系统中插入(创造)一个新的用户,大家得以接纳:

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

 

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

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

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

 

  上面是对成品有关的ULX570I的一对提议:

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

  用于成立新的出品。

 

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

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

 

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

  一种方案是:

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

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

  

  因为我们想为用户创制1个订单(注意之间的涉及),这么些U奥迪Q5I或然不够直观,上边这一个UHighlanderI则更鲜美赞臣(Meadjohnson)些:

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

  未来我们知道它是为编号33245的用户成立四个订单。

 

  那下边那些请求重临的是哪些啊?

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

  只怕是三个编号为33245的用户所制造或具备的订单列表。注意:大家可以遮挡对该UHavalI举办DELETE或PUT请求,因为它的操作对象是2个聚众。

 

  继续深刻,那下边那些U奥迪Q7I的乞求又代表怎样啊?

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

  大概是(为编号33245的用户)扩展二个数码为8769的订单条目。没错!如若接纳GET格局呼吁这一个UEvoqueI,则会回去这几个订单的持有条条框框。然而,借使那几个条款与用户消息无关,我们将会提供POST
www.example.com/orders/8769/lineitems
这个URI。

  从再次回到的那么些条款来看,内定的能源或然会有八个U凯雷德Is,所以大家只怕也急要求提供这么三个U兰德昂科拉I
GET
http://www.example.com/orders/8769
,用来在不知底用户ID的情状下基于订单ID来询问订单。

 

  更进一步:

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

  恐怕只回去同个订单中的首个条目。

  以后您应该了然什么是分层结构了。它们并不是严苛的平整,只是为了确认保证在你的劳务中这么些强制的布局可以更便于被用户所知晓。与持有软件开发中的技能一样,命名是打响的第2。

  

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

能源命名的反例

  前面大家曾经商讨过部分老少咸宜的财富命名的例证,不过有时一些反面包车型大巴事例也很有教育意义。上面是一对不太具有RESTful风格的能源UOdysseyIs,看起来比较混乱。那几个都以漏洞百出的例子! 

  首先,一些serivices往往选拔单一的U锐界I来钦命服务接口,然后经过询问参数来钦点HTTP请求的动作。例如,要立异编号12345的用户音讯,带有JSON
body的呼吁或者是如此:

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

  就算地方USportageL中的”services”的那么些节点是3个名词,但以此UKoleosL不是自解释的,因为对于拥有的央浼而言,该UCR-VI的层级结构都以平等的。另外,它选择GET作为HTTP动词来实施二个更新操作,这简直正是反人类(甚至是千钧一发的)。

  上边是此外三个翻新用户的操作的例子:

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

  以及它的一个变种:

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

  你会平常见到在任何开发者的劳动套件中有许多这么的用法。能够看到,这个开发者试图去创立RESTful的能源名称,而且早已有了有的上扬。不过你仍是能够够分辨出U君越L中的动词短语。注意,在那一个UEvoqueL中大家不需求”update”那些词,因为大家得以凭借HTTP动词来成功操作。下边这一个U哈弗L正好表达了那一点:

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

  这些请求同时存在PUT和”update”,那会对消费者发生迷惑!那里的”update”指的是叁个能源吗?由此,那里大家费些口舌也是可望你能够精通……

财富命名的反例

  前边大家曾经研讨过局地适龄的财富命名的例证,可是有时一些反面包车型地铁事例也很有教育意义。下边是一对不太具有RESTful风格的能源ULANDIs,看起来相比较散乱。这一个都是荒唐的事例! 

  首先,一些serivices往往选用单一的U本田UR-VI来钦点服务接口,然后通过查询参数来钦点HTTP请求的动作。例如,要翻新编号12345的用户音信,带有JSON
body的央浼可能是那般:

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

  即使地点U昂CoraL中的”services”的那个节点是一个名词,但以此U卡宴L不是自解释的,因为对于拥有的央求而言,该U福睿斯I的层级结构都以同样的。其余,它选择GET作为HTTP动词来实施一个立异操作,那大约正是反人类(甚至是生死攸关的)。

  下边是别的贰个翻新用户的操作的例子:

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

  以及它的二个变种:

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

  你会时不时见到在其余开发者的服务套件中有诸多如此的用法。能够观察,这一个开发者试图去创设RESTful的能源名称,而且早已有了有个别迈入。不过你还可以够分辨出U大切诺基L中的动词短语。注意,在那一个UHavalL中大家不需求”update”那么些词,因为大家得以重视HTTP动词来形成操作。下边那一个UPAJEROL正好表明了这点:

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

  那些请求同时设有PUT和”update”,那会对顾客爆发迷惑!那里的”update”指的是贰个能源吗?由此,那里我们费些口舌也是期望你能够明白……

复数

  让大家来探讨一下复数和“单数”的争持…还没听闻过?但那种争议确实存在,事实上它可以归咎为那一个题材……

  在你的层级结构中U昂科威I节点是或不是必要被取名为单数或复数方式呢?举个例子,你用来探寻用户财富的U中华VI的命名是还是不是须要像上边那样:

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

  或者:

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

  二种办法都没难题,但常见大家都会挑选使用复数命名,以使得你的API
U冠道I在装有的HTTP方法中保持一致。原因是基于那样一种考虑:customers是劳动套件中的三个集聚,而ID33245的那一个用户则是其一集合中的当中贰个。

  遵照那些规则,1个选用复数格局的多节点的ULX570I会是这么(注意粗体部分):

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

  “customers”、“orders”以及“lineitems”那一个UKugaI节点都采取的是复数方式。

  这象征你的各类根财富只供给多个基本的U安德拉L就能够了,四个用来创制集合内的财富,另3个用来依据标识符获取、更新和删除能源。例如,以customers为例,创造财富得以选拔下边包车型客车UQX56L举办操作:

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

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

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

  正如前方提到的,给定的能源恐怕有八个U酷路泽I,但作为一个小小的完全的增加和删除改查成效,利用四个简易的UEnclaveI来拍卖就够了。

  或者你会问:是或不是在多少意况下复数没有意思?嗯,事实上是这样的。当没有集合概念的时候(此时复数没有意思)。换句话说,当能源只有八个的状态下,使用单数财富名称也是足以的——即二个单一的财富。例如,借使有二个纯粹的完全体署财富,你能够应用三个单数名称来表示:

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

  注意那里缺乏configuration的ID以及HTTP动词POST的用法。倘使每一种用户有一个布置来说,那么那个UPRADOL会是这么:

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

  同样令人瞩目那里没有点名configuration的ID,以及从未给定POST动词的用法。在那多个例子中,或许也会有人以为采取POST是实惠的。好吧…

 

复数

  让大家来商讨一下复数和“单数”的争持…还没据书上说过?但那种争议确实存在,事实上它可以归咎为那么些难题……

  在您的层级结构中U劲客I节点是还是不是要求被命名为单数或复数情势呢?举个例证,你用来探寻用户财富的U奥迪Q3I的命名是还是不是供给像上边那样:

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

  或者:

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

  二种艺术都没难点,但常见大家都会选择使用复数命名,以使得你的API
U陆风X8I在装有的HTTP方法中保持一致。原因是基于这样一种考虑:customers是劳动套件中的1个集聚,而ID33245的这么些用户则是其一集合中的个中3个。

  遵照那个规则,三个接纳复数情势的多节点的ULANDI会是那般(注意粗体部分):

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

  “customers”、“orders”以及“lineitems”那么些U景逸SUVI节点都施用的是复数方式。

  那代表你的每一个根能源只须要三个着力的URAV4L就能够了,二个用以创立集合内的财富,另1个用来依据标识符获取、更新和删除财富。例如,以customers为例,创建能源得以选拔上边包车型大巴U凯雷德L进行操作:

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

  而读取、更新和删除财富,使用上面包车型大巴U奥德赛L操作:

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

  正如前方提到的,给定的资源可能有五个U奇骏I,但作为一个相当小的完整的增加和删除改查作用,利用七个简单的U汉兰达I来处理就够了。

  或然你会问:是不是在多少境况下复数没有意义?嗯,事实上是那样的。当没有集合概念的时候(此时复数没有意义)。换句话说,当资源唯有三个的图景下,使用单数财富名称也是能够的——即三个单一的财富。例如,倘使有一个纯净的完好计划财富,你能够选取3个单数名称来表示:

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

  注意那里贫乏configuration的ID以及HTTP动词POST的用法。假若每种用户有多少个安排来说,那么那些UPRADOL会是那般:

  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牧马人I中钦赐重返表征的格式,能够增进UTiggoL的可知性。例如,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头,服务端要同时协理封装和未封装的响应,你无法不完成自定义的品种——因为这么些格式不是明媒正娶的花色。那大大增添了客户端和服务端的复杂性。请参见中华VFC
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中钦点再次回到表征的格式,能够压实U库罗德L的可知性。例如,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头,服务端要同时协助封装和未封装的响应,你不可能不兑现自定义的类别——因为那些格式不是正经的品类。那大大扩充了客户端和服务端的错综复杂。请参见RubiconFC
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是什么”一节中也关乎过。

  依照罗伊菲尔德ing在她的博客中的描述(http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertextdriven),REST接口中最要紧的某些是超文本的利用。其它,他还建议,在付给任何有关的新闻在此之前,三个API应该是可用和可见道的。也便是说,1个API应当能够透过其链接导航到数码的各样部分。不提出只回去纯数据。

  不过当下的产业界先驱们并从未常常使用这种做法,那反映了HATEOAS仅仅在成熟度模型中的使用率更高。纵观者多的服务体系,它们基本上重返越多的数额,而回到的链接却很少(恐怕没有)。那是违反Fielding的REST约定的。Fielding说:“消息的每二个可寻址单元都指引三个地方……查询结果应当展现为多个饱含摘要新闻的链接清单,而不是目标数组。”

  另一方面,不难冷酷地将全体链接集合再次来到会大大影响网络带宽。在实际意况中,依照所需的标准化或利用意况,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应该是可用和可领会的。约等于说,二个API应当能够透过其链接导航到数码的逐条部分。不建议只回去纯数据。

  可是当下的产业界先驱们并不曾常常使用那种做法,那显示了HATEOAS仅仅在成熟度模型中的使用率更高。纵观者多的服务种类,它们大多再次来到更多的数量,而回到的链接却很少(或许尚未)。那是违背Fielding的REST约定的。Fielding说:“消息的每3个可寻址单元都指点二个地点……查询结果应该展现为3个包含摘要音信的链接清单,而不是指标数组。”

  另一方面,简单凶残地将全方位链接集合重回会大大影响网络带宽。在其实际情景况中,依照所需的基准或应用处境,API接口的通讯量要基于服务器响应中国足球组织一流联赛文本链接所包罗的“摘要”数量来平衡。

  同时,足够利用HATEOAS或许会扩展落成的错综复杂,并对服务客户端产生分明的承负,这一定于降低了客户端和劳动器端开发职员的生产力。因而,当务之急是要平衡超链接服务实施和现有可用能源之间的难点。

  超链接最小化的做法是在最大限度地回落客户端和服务器之间的耦合的还要,进步服务端的可用性、可操纵性和可领会性。这么些最小化提议是:通过POST创制财富并从GET请求重返集合,对于有分页的动静前边大家会涉及。

微小化链接推荐

  在create的用例中,新建能源的U路虎极光I(链接)应该在Location响应头中回到,且响应中央是空的——或许只包含新建财富的ID。

  对于从服务端再次回到的性状集合,每一种表征应该在它的链接集合中带走三个细小的“自己”链接属性。为了便利分页操作,此外的链接能够放在一个单身的链接集合中回到,须求时得以分包“第3页”、“上一页”、“下一页”、“最终一页”等音信。

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

小小化链接推荐

  在create的用例中,新建能源的U途乐I(链接)应该在Location响应头中回到,且响应中央是空的——大概只含有新建能源的ID。

  对于从服务端再次来到的特色集合,每一种表征应该在它的链接集合中带走二个一点都不大的“自个儿”链接属性。为了有利于分页操作,其它的链接能够放在1个独立的链接集合中回到,要求时得以分包“第2页”、“上一页”、“下一页”、“最终一页”等音讯。

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

链接格式

  参照整个链接格式的正规,指出遵循一些像样Atom、AtomPub或Xlink的风骨。JSON-LD也合情合理,但并不曾被大规模运用(要是已经被用过)。最近正规最常见的主意是选用带有”rel”元素和包涵资源总体URI的”href”成分的Atom链接格式,不含有其余身份验证或询问字符串参数。”rel”成分得以包含标准值”alternate”、”related”、”self”、”enclosure”和”via”,还有分页链接的“第③页”、“上一页”、“下一页”,“最后一页”。在急需时得以自定义并加上应用它们。

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

  让我们举一些具体的事例来更是印证这点。上边是调用创制新资源的请求后的响应:

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

  上边是响应头集合中包蕴制造新资源的U奥迪Q5I的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请求获取1个不带有分页的个性集合的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请求获取2个饱含分页的特征集合的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集合;另1个则是八个独门的指标links,个中囊括和分页相关的链接,该片段的始末适用于一切集合。

  对于由此POST请求创制能源的景况,要求在响应头中包罗1个关联新建对象链接的Location

链接格式

  参照整个链接格式的正儿八经,建议遵循一些好像Atom、AtomPub或Xlink的风骨。JSON-LD也没错,但并没有被大规模运用(若是已经被用过)。方今正式最常见的法子是使用带有”rel”成分和包涵能源总体URI的”href”成分的Atom链接格式,不含有其余身份验证或询问字符串参数。”rel”成分得以包括标准值”alternate”、”related”、”self”、”enclosure”和”via”,还有分页链接的“第2页”、“上一页”、“下一页”,“最终一页”。在急需时得以自定义并累加应用它们。

  一些XML
Atom格式的定义对于用JSON格式表示的链接来说是于事无补的。例如,METHOD属性对于1个RESTful能源来说是不须求的,因为对于1个加以的能源,在颇具帮忙的HTTP方法(CRUD行为)中,财富的UMuranoI都是同等的——所以单独列出那几个是从未供给的。

  让我们举一些现实的例子来一发验证那点。上边是调用创制新能源的乞求后的响应:

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

  下边是响应头集合中富含创制新能源的U奥迪Q5I的Location部分:

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

  重临的body能够为空,或然隐含多个被装进的响应(见下文封装响应)。

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

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

  注意,links数组中的每一项都包括贰个对准“本人(self)”的链接。该数组还恐怕还带有别的关系,如children、parent等。

  最后七个例子是经过GET请求获取3个分包分页的特征集合的JSON响应(每页展现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请求创设能源的图景,须求在响应头中包括3个涉及新建对象链接的Location

包裹响应

   服务器能够在响应中而且重返HTTP状态码和body。有诸多JavaScript框架没有把HTTP状态响应码重返给最终的开发者,那往往会招致客户端不可能依照情形码来分明具体的作为。别的,纵然HTTP规范中有很多样响应码,不过往往只某些客户端会关注这么些——平时大家只在乎”success”、”error”或”failture”。因而,将响应内容和响应状态码封装在包蕴响应新闻的风味中,是有必不可少的。

  OmniTI
实验室有这么四个建议,它被称作JSEND响应。更加多新闻请参考http://labs.omniti.com/labs/jsend。其余1个提案是由DouglasCrockford建议的,能够查看那里http://www.json.org/JSONRequest.html

  这几个提案在实践中并没有完全涵盖全数的情状。基本上,未来最好的做法是服从以下属性封装常规(非JSONP)响应:

  • code——包涵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)标准,它能够涵盖音信号大概编码,能够只含有在那之中一个,大概同时含有并用分隔符隔开分离。
  • 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本田CR-VS)。JSONP或“填充的JSON”是一种选取情势,它提供了二个格局请求来自分裂域中的服务器的多寡。其工作章程是从服务器再次来到任意的JavaScript代码,而不是JSON。客户端的响应由JavaScript解析器进行分析,而不是直接解析JSON数据。此外,COSportageS是一种web浏览器的技巧标准,它为web服务器定义了一种方式,从而允许服务器的财富可以被分化域的网页访问。COOdysseyS被当做是JSONP的最新替代品,并且能够被有着现代浏览器帮衬。由此,不提议采用JSONP。任何情形下,推荐选用CORS。

拍卖跨域难题

   大家都听别人讲过有关浏览器的同源策略或同源性供给。它指的是浏览器只可以请求当前正值展现的站点的能源。例如,如若当前正在展现的站点是www.Example1.com,则该站点不能够对www.Example.com倡议呼吁。显明那会影响站点访问服务器的方法。

  近期有七个被广泛接受的帮衬跨域请求的不二法门:JSONP和跨域财富共享(CO哈弗S)。JSONP或“填充的JSON”是一种选用方式,它提供了3个措施请求来自区别域中的服务器的数额。其工作措施是从服务器再次来到任意的JavaScript代码,而不是JSON。客户端的响应由JavaScript解析器进行分析,而不是直接解析JSON数据。此外,COSportageS是一种web浏览器的技巧标准,它为web服务器定义了一种方式,从而允许服务器的财富得以被分裂域的网页访问。COEscortS被当做是JSONP的最新替代品,并且可以被抱有现代浏览器协理。由此,不建议采纳JSONP。任何景况下,推荐采用CO冠道S。

支持CORS

  在服务端达成CO汉兰达S一点也不细略,只必要在发送响应时顺手HTTP头,例如: 

Access-Control-Allow-Origin: *

  唯有在多少是国有使用的状态下才会将做客来源设置为”*”。大多数景况下,Access-Control-Allow-Origin头应该钦命哪些域能够倡导3个CO酷路泽S请求。只有须要跨域访问的U本田UR-VL才设置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服务器上计划二个用空格分隔的域的列表。越来越多关于CO奥迪Q7S的内容可以参见那里:http://enable-cors.org/

支持CORS

  在服务端完毕CO本田UR-VS非常的粗略,只要求在发送响应时顺手HTTP头,例如: 

Access-Control-Allow-Origin: *

  只有在数码是公物使用的事态下才会将访问来源设置为”*”。大部分动静下,Access-Control-Allow-Origin头应该钦赐哪些域能够倡导3个CO福特ExplorerS请求。唯有需求跨域访问的UGL450L才设置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服务器上配置七个用空格分隔的域的列表。更加多关于COKoleosS的始末能够参考那里:http://enable-cors.org/

支持JSONP

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

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

  JSONP平时在有的不支持CO福特ExplorerS的老旧浏览器中应用,假设要改成援救CO陆风X8S的,会影响整个服务器的架构。大概大家也足以因此代理来落到实处JSONP。总而言之,JSONP正在被CO安德拉S所代替,大家应有尽只怕地行使COLacrosseS。

  为了在服务端协理JSONP,在JSONP字符串查询参数字传送递时,响应必须求推行以下那几个操作:

  1. 响应体必须封装成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请求避开浏览器的限量,从而达成对持有服务的调用。其行事规律是请求方在呼吁的UPRADOL上添加一个字符串查询参数(例如:jsonp=”jsonp_callback”),当中“jsonp”参数的值是JavaScript函数名,该函数在有响应重返时将会被调用。

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

  JSONP平时在有的不协助CO奥德赛S的老旧浏览器中选取,假若要改成扶助COOdysseyS的,会影响整个服务器的架构。恐怕我们也足以经过代办来落到实处JSONP。总之,JSONP正在被CO本田UR-VS所取代,大家应有尽可能地选拔COGL450S。

  为了在服务端帮忙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'}")

 

询问,过滤和分页

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

  除了限制再次回到的数据量,大家还必要考虑什么对时局据集举行“分页”或下拉滚动操作。成立数量的“页码”,再次回到大数量列表的已知片段,然后标出数据的“前一页”和“后一页”——这一行事被喻为分页。其余,大家恐怕也须求钦赐响应元帅包蕴怎样字段或性质,从而限制重回值的数目,并且大家目的在于最终能够由此特定值来举办查询操作,并对再次来到值举行排序。

  有三种关键的措施来还要限制查询结果和实践分页操作。首先,大家得以成立多个索引方案,它能够以页码为导向(请求中要交给每一页的记录数及页码),可能以记录为导向(请求中平昔提交第1条记下和最后一条记下)来规定重回值的发端地方。举个例子,那二种方式分别代表:“给出第④页(借使每页有20条记下)的记录”,或“给出第十0到第二20条的笔录”。

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

  下文将介绍一种办法,既能够辅助Dojo那样的分页情势(在请求头中付出记录的限量),也能支撑使用字符串查询参数。这样一来服务端将变得特别灵活,既能够接纳类似Dojo一样先进的UI工具集,也能够运用简单直接的链接和标签,而无需再为此扩张复杂的付出工作。但如若服务不直接帮助UI成效,能够设想不要在请求头中付出记录范围。

  要越发提议的是,大家并不推荐在全体服务中应用查询、过滤和分页操作。并不是具有能源都暗许扶助那一个操作,唯有某个特定的资源才支撑。服务和资源的文书档案应当表达什么接口协助这一个扑朔迷离的效率。

查询,过滤和分页

  对于大数据集,从带宽的角度来看,限制重临的数据量是特别首要的。而从UI处理的角度来看,限制数据量也一律非同平日,因为UI日常只好呈现大数额汇总的一小部分数目。在数据集的增速不鲜明的景观下,限制暗许重临的数据量是很有必不可少的。以推特为例,要博得有个别用户的推文(通过个人主页的时日轴),假若没有专门钦定,请求默许只会重回20条记下,即使系统最多能够回来200条记下。

  除了限制重返的数据量,大家还索要考虑如何对天意据集进行“分页”或下拉滚动操作。成立数量的“页码”,重返大数目列表的已知片段,然后标出数据的“前一页”和“后一页”——这一表现被称作分页。别的,大家恐怕也亟需钦命响应团长包蕴哪些字段或质量,从而限制再次来到值的数据,并且我们盼望最终能够透过一定值来拓展查询操作,并对重返值实行排序。

  有二种关键的方法来还要限定查询结果和施行分页操作。首先,大家得以创制三个索引方案,它能够以页码为导向(请求中要付出每一页的记录数及页码),大概以记录为导向(请求中央直机关接交给第3条记下和末段一条记下)来分明再次回到值的苗子地方。举个例子,那二种办法分别代表:“给出第四页(假若每页有20条记下)的记录”,或“给出第⑧0到第二20条的笔录”。

  服务端将依照运作体制来进展切分。某个UI工具,比如Dojo
JSON会采取模仿HTTP规范行使字节范围。假如服务端扶助out of
box(即开箱即用功效),则前端UI工具和后端服务中间无需任何转换,那样使用起来会很便利。

  下文将介绍一种艺术,既能够补助Dojo那样的分页格局(在请求头中付出记录的限制),也能支撑采纳字符串查询参数。那样一来服务端将变得更为灵活,既能够动用类似Dojo一样先进的UI工具集,也得以使用简易直接的链接和标签,而无需再为此扩张复杂的支付工作。但假若服务不直接协助UI功用,能够设想不要在请求头中提交记录范围。

  要专门建议的是,大家并不推荐在全体服务中运用查询、过滤和分页操作。并不是具备能源都暗许帮忙那个操作,唯有有个别特定的能源才支撑。服务和能源的文书档案应当表明什么接口支持这几个纷纷的功用。

结果限制

  “给出第一到第④5条的记录”,那种请求数据的形式和HTTP的字节范围规范更平等,由此大家能够用它来标识Range
header。而“从第贰条记下开头,给出最多20条记下”这种方法更便于阅读和驾驭,因而大家平常会用字符串查询参数的法子来代表。

  综上所述,推荐既扶助使用HTTP Range
header,也支撑接纳字符串查询参数——offset(偏移量)和limit(限制),然后在服务端对响应结果实行限制。注意,假若还要协理那三种办法,那么字符串查询参数的优先级要高于Range
header。

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

  由此可知,解析Range
header的工作会扩展复杂度,相应的客户端在构建请求时也亟需开始展览局地甩卖。而选取单独的limit和offset参数会愈来愈便于掌握和构建,并且不须要对开发人士有越多的须求。

结果限制

  “给出第二到第45条的记录”,那种请求数据的法子和HTTP的字节范围规范更平等,由此大家得以用它来标识Range
header。而“从第①条记下伊始,给出最多20条记下”那种措施更便于阅读和清楚,由此大家家常便饭会用字符串查询参数的方法来代表。

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

  那里您可能会有个疑问:“那三种艺术效果相似,然则回到的数码不完全一致。那会不会令人歪曲呢?”恩…那是多少个难题。首先要应对的是,那确实会令人歪曲。关键是,字符串查询参数看起来更为清晰易懂,在构建和分析时越发有利于。而Range
header则越多是由机械来利用(偏向于底层),它更是符合HTTP使用正规。

  总而言之,解析Range
header的工作会扩展复杂度,相应的客户端在创设请求时也急需展开一些处理。而采用单独的limit和offset参数会越来越不难精通和创设,并且不供给对开发人士有更加多的供给。

用范围标记实行限定

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

  Range: items=0-24

  注意记录是从0初始的接连字段,HTTP规范中证实了怎么行使Range
header来请求字节。也正是说,假若要呼吁数据汇总的首先条记下,范围应当从0起初算起。上述的伸手将会回来前2多少个记录,就算数据集中至少有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第③个数字同样),limit代表记录的最大条数。上边包车型客车例子再次来到的结果与上述用范围标记的例证一样:

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

  Offset参数的值与Range
header中的类似,也是从0早先总括。Limit参数的值是回去记录的最大数额。当字符串查询参数中未钦命limit时,服务端应当交付二个缺省的最大limit值,不过那些参数的应用都亟需在文书档案中开展表达。

用字符串查询参数进行界定

  字符串查询参数被当作Range
header的替代选拔,它利用offset和limit作为参数名,在那之中offset代表要询问的第1条记下编号(与上述的用于范围标记的items首个数字同样),limit代表记录的最大条数。下边包车型地铁例证再次来到的结果与上述用范围标记的事例一样:

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

  Offset参数的值与Range
header中的类似,也是从0开端总结。Limit参数的值是回来记录的最大数目。当字符串查询参数中未内定limit时,服务端应当提交三个缺省的最大limit值,不过这几个参数的施用都需求在文书档案中开始展览验证。

依据范围的响应

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

传闻范围的响应

  对2个根据范围的呼吁来说,无论是通过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

  在大部情况下,那种分页格局都不曾难题。但有时会有那种景况,正是要赶回的记录数据不能够直接代表成数据集中的行号。还有正是有个别数据集的转移相当慢,不断会有新的多寡插入到数量集中,那样必然会造成分页现身难点,一些双重的数目或然会现出在不相同的页中。

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

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

  假使请求时不曾点名要重回的数额范围,服务端再次回到了一组暗中同意数据或限制的最大数据集,那么服务端同时也理应在回来结果中带有Content-Range
header来和客户端举行确认。以地方个人主页的年华轴为例,无论客户端是还是不是钦定了Range
header,服务端每便都只回去20条记下。此时,服务端响应的Content-Range
header应该包罗如下内容:

  Content-Range: 0-19/4125

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

分页

  上述方法经过请求方钦赐数据集的界定来界定重回结果,从而完毕分页成效。上边的例子中一共有66条记下,假若每页25条记下,要展现第贰页数据,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等相结合,可以兑现强大的数据检索功用。

  再强调1遍,过滤和排序都是叶影参差的操作,不须求暗中同意提须求全数的财富。下文将介绍如何能源须求提供过滤和排序。

结果的过滤和排序

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

  再强调一遍,过滤和排序都是复杂的操作,不须求暗中认可提供给拥有的财富。下文将介绍怎么着能源供给提供过滤和排序。

过滤

  在本文中,过滤被定义为“通过一定的标准来规定必须求回来的多少,从而裁减再次回到的多寡”。假如服务端帮助一套完整的比较运算符和复杂性的规则优秀,过滤操作将变得格外复杂。不过大家一般会利用一些简约的表明式,如starts-with(以…伊始)或contains(包蕴)来展开匹配,以确定保障重回数据的完整性。

  在大家初步讨论过滤的字符串查询参数此前,必须先明了为何要运用单个参数而不是多少个字符串查询参数。从根本上来说是为了减小参数名称的争辩。大家早已有offsetlimitsort(见下文)参数了。如果大概的话还会有jsonpformat标识符,可能还会有afterbefore参数,这几个都以在本文中涉及过的字符串查询参数。字符串查询中动用的参数更加多,就越可能导致参数名称的争辨,而选取单个过滤参数则会将争持的恐怕性降到最低。

  别的,从服务端也很不难仅经过单个的filter参数来判断请求方是不是须求多少过滤效果。借使查询要求的复杂度扩张,单个参数将更具备灵活性——可以本身树立一套功用完全的查询语法(详见下文OData注释或访问http://www.odata.org)。

  通过引入一组广泛的、公认的分隔符,用于过滤的表明式能够以12分直观的款式被采取。用那个分隔符来设置过滤查询参数的值,这个分隔符所创造的参数名/值对能够特别便于地棉被和衣服务端解析并增强多少查询的习性。近期已某些分隔符包蕴用来分隔每一个过滤短语的竖线(”|”)和用来分隔参数名和值的双冒号(”::”)。那套分隔符丰富唯一,并符合超过半数境况,同时用它来塑造的字符串查询参数也特别简单掌握。上边将用1个简易的例子来介绍它的用法。就算大家想要给名为“托德”的用户们发送请求,他们住在金奈,有着“Grand
Poobah”之称。用字符串查询参数实现的哀告URAV4I如下:

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

过滤

  在本文中,过滤被定义为“通过特定的标准化来规定必须要再次回到的多少,从而收缩再次回到的多寡”。要是服务端协助一套完整的可比运算符和错综复杂的尺度格外,过滤操作将变得12分复杂。可是大家一般会采用一些简单易行的表明式,如starts-with(以…开端)或contains(包涵)来进展匹配,以保障再次来到数据的完整性。

  在我们起首谈论过滤的字符串查询参数从前,必须先掌握为何要利用单个参数而不是五个字符串查询参数。从根本上来说是为着减小参数名称的争持。大家早就有offsetlimitsort(见下文)参数了。如若大概的话还会有jsonpformat标识符,大概还会有afterbefore参数,这么些都以在本文中提到过的字符串查询参数。字符串查询中运用的参数越多,就越大概引致参数名称的冲突,而利用单个过滤参数则会将争持的恐怕性降到最低。

  别的,从服务端也很不难仅透过单个的filter参数来判断请求方是不是必要多少过滤效果。假诺查询需求的复杂度扩张,单个参数将更拥有灵活性——能够友善树立一套效率完全的查询语法(详见下文OData注释或访问http://www.odata.org)。

  通过引入一组广泛的、公认的分隔符,用于过滤的表明式能够以那两个直观的情势被采取。用这几个分隔符来设置过滤查询参数的值,这几个分隔符所创建的参数名/值对能够更进一步简单地棉被和衣服务端解析并进步多少查询的性质。目前已部分分隔符包涵用来分隔每一种过滤短语的竖线(”|”)和用来分隔参数名和值的双冒号(”::”)。那套分隔符丰硕唯一,并符合大多数气象,同时用它来创设的字符串查询参数也尤其便于掌握。上面将用一个简短的例子来介绍它的用法。假若大家想要给名为“托德”的用户们发送请求,他们住在圣路易斯,有着“Grand
Poobah”之称。用字符串查询参数实现的请求ULANDI如下:

  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来展现,客户端会由于差异的版本而接受到区别的质量。那样就会设有一些难点,如从内容自身和表达规则方面改变了1个已存在的性情的意思。

  当然,大家无能为力防止API恐怕在好何时候须求转移再次来到数据的格式和剧情,而那也将造成消费端的部分浮动,大家应当制止举办一些重中之重的调整。将API实行版本化管理是幸免那种首要变动的一种有效方式。

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

  现在,版本管理通过ULANDI本人的版本号来成功,客户端在呼吁的U奇骏I中标明要获取的财富的版本号。事实上,许多大商店如Facebook、Yammer、Twitter、谷歌等不时在她们的U卡宴I里使用版本号。甚至像WSO2那样的API管理工科具也会在它的U奥迪Q3Ls中供给版本号。

  面向REST原则,版本管理技术飞速发展。因为它不包括HTTP规范中置放的header,也不帮助仅当1个新的能源或概念被引入时才应该添加新U奥迪Q3I的见识——即版本不是表现格局的转移。另二个不予的理由是能源UPAJEROI是不会随时间改变的,财富便是能源。

  U冠道I应该能大致地识别能源——而不是它的“形状”(状态)。另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在发送数据给服务器时的用处,那里给出1个用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自己的版本号来形成,客户端在恳求的UEvoqueI中标明要取得的能源的版本号。事实上,许多大商店如Instagram、Yammer、推特(TWTR.US)(TWTPRADO.US)、谷歌等不时在她们的U奔驰M级I里使用版本号。甚至像WSO2那样的API管理工科具也会在它的UEvoqueLs中供给版本号。

  面向REST原则,版本管理技术急迅发展。因为它不带有HTTP规范中放到的header,也不援救仅当1个新的财富或概念被引入时才应该添加新U奥迪Q5I的见地——即版本不是表现格局的变迁。另一人演唱会对台戏的理由是财富UENCOREI是不会随时间改变的,财富正是能源。

  UMuranoI应该能大概地辨认财富——而不是它的“形状”(状态)。另三个就是必须钦赐响应的格式(表征)。还有局地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奥迪Q5I是怎么样实今后区别的版本中分辨能源的。或然,借使客户端需求二个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在发送数据给服务器时的用途,那里给出1个用JSON格式创制新用户的事例:

  #Request

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

  {“name”:”Marco Polo”}

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

  #Request

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

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

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

  并不须求在每一个呼吁中都钦命版本号。由于HTTP
content-negotiation(内容协商)遵循类型的“最佳匹配”格局,所以你的API也应有根据那或多或少。依照这一规则,当客户端从未点名版本时,API应当再次来到所支撑的最早版本。

  仍然那一个例子,获取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情势向服务器发送数据时,倘使服务器接济多个例外版本,而请求时又从未点名版本,和上边的例子一样——服务器会将小小/最早版本的数额包罗在body中。为了实行求证,上面包车型大巴例子以JSON格式请求2个带有多版本财富的服务器,来创造贰个新用户(预期会回来版本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格式请求二个分包多版本财富的服务器,来成立2个新用户(预期会回到版本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还应该再次回到1个蕴涵Content-Type:
application/json的响应体,个中包括1个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应当再次回到1个荒谬的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的财富,以前表示的是兼具接济的媒体类型的3个”links”集合,而新的text/html则代表的是用户输入的“web浏览器表单”。
    • 二个带有”endTime”参数的API,对财富”…/users/{id}/exams/{id}”说明的意义是学员在丰裕时间付诸试卷,而新的意思则是考查的预订达成时间。
  • 经过丰盛新的字段来改变现有的财富。将多个财富统一为2个并弃用原始的资源。
    • 有如此七个财富”…/users/{id}/dropboxBaskets/{id}/messages/{id}”和”…/users/{id}/dropboxBaskets/{id}/messages/{id}/readStatus”。新需要是把readStatus财富的性质放到单独的message能源中,并弃用readStatus能源。那将招致messages能源中指向readStatus能源的链接被移除。

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

破坏性的修改

  • 改变属性名(例如将”name”改成”firstName”)
  • 剔除属性
  • 转移属性的数据类型(例如将numeric变为string,
    boolean变为bit/numeric,string 变为 datetime等等)
  • 变动验证规则
  • 在Atom样式的链接中,修改”rel”的值
  • 在现有的工作流中引入需求财富
  • 更改财富的定义/意图;概念/意图或能源气象的含义区别于它原本的意义。例如:
    • 3个content
      type是text/html的能源,在此以前表示的是有着支持的传播媒介类型的3个”links”集合,而新的text/html则象征的是用户输入的“web浏览器表单”。
    • 五个富含”endTime”参数的API,对资源”…/users/{id}/exams/{id}”表明的意思是学员在特别时刻付诸试卷,而新的含义则是考查的约定完结时间。
  • 经过抬高新技术的字段来改变现有的财富。将三个能源统一为2个并弃用原始的能源。
    • 有诸如此类七个能源”…/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来增加响应

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

采纳Content-Location来拉长响应

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

带有Content-Type的链接

  Atom风格的链接援助”type”属性。提供丰盛的消息以便客户端可以对一定的本子和内容类型进行调用。

带有Content-Type的链接

  Atom风格的链接支持”type”属性。提供丰硕的新闻以便客户端能够对特定的版本和剧情类型实行调用。

找出帮忙的版本

找出扶助的版本

自笔者应该而且帮忙多少个本子?

  维护七个不等的版本会让劳作变得繁琐、复杂、简单失误,而且代价高,对于此外给定的财富,你应当援助不超越3个版本。

自家应当同时帮忙多少个版本?

  维护多个例外的本子会让工作变得繁琐、复杂、简单出错,而且代价高,对于其余给定的资源,你应该援助不抢先一个本子。

弃用

  Deprecated(弃用)的指标是用来验证能源对API依旧可用,但在前天会不设有并变得不可用。在意:弃用的时间长度将由弃用政策决定——那里并不曾交到定义。

弃用

  Deprecated(弃用)的指标是用来表明能源对API还是可用,但在以往会不存在并变得不可用。小心:弃用的时长将由弃用政策决定——那里并不曾提交定义。

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

  许多客户端未来访问的能源恐怕在新本子引入后会被扬弃掉,因而,他们要求有一种艺术来发现和监察和控制他们的应用程序对弃用能源的选取。当呼吁1个弃用能源时,API应该健康响应,并涵盖三个布尔类型的自定义Header
“Deprecated”。以下用3个事例来开始展览求证。

  #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应该健康响应,并含有3个布尔类型的自定义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中是以字符串的格式存在的,如若未钦点统一的格式,那么解析日期也会是2个标题。

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

日子/时间处理

  假使没有妥当地、一致地拍卖好日期和时间的话,那将成为叁个大麻烦。大家平时会境遇时区的难题,而且由于日期在JSON中是以字符串的格式存在的,假若未钦命统一的格式,那么解析日期也会是三个标题。

  在接口内部,服务端应该以UTC或GMT时间来储存、处理和缓存时间戳。那将实惠缓解日期和岁月的难点。

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

  有3个简便的点子能够缓解那一个题材——在字符串中始终用同样的格式,蕴含时间片(带有时区新闻)。ISO8601时间格式是二个不利的缓解方案,它采纳了完全增强的小运格式,包含小时、分钟、秒以及秒的小数部分(例如yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)。提议在REST服务的body内容中(请求和响应均包含)使用ISO8601代表全数的日子格式。

  顺便提一下,对于那个基于JAVA的劳务以来,DateAdapterJ库使用DateAdapter,Iso8601提姆epointAdapter和HttpHeaderTimestampAdapter类可以相当简单地分析和格式化ISO860十日期和岁月,以及HTTP
1.1
header(GL450FC1123)格式。能够从https://github.com/tfredrich/DateAdapterJ下载。

  对于那个成立基于浏览器的用户界面来说,ECMAScript5专业一开头就包蕴了JavaScript解析和创制ISO860二十八日期的始末,所以它应该成为我们所说的主流浏览器所遵守的方式。当然,如若你要援助那3个不可能自动解析日期的旧版浏览器,能够采用JavaStript库或正则表明式。那里有多少个能够分析和开创ISO8601时间的JavaStript库:

  http://momentjs.com/

  http://www.datejs.com/

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

  有一个回顾的办法能够消除那几个题材——在字符串中一贯用相同的格式,蕴涵时间片(带有时区音讯)。ISO8601时间格式是3个不错的消除方案,它利用了完全增强的时间格式,包蕴小时、秒钟、秒以及秒的小数部分(例如yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)。提出在REST服务的body内容中(请求和响应均包括)使用ISO8601代表全体的日子格式。

  顺便提一下,对于那些基于JAVA的劳务以来,DateAdapterJ库使用DateAdapter,Iso8601提姆epointAdapter和HttpHeaderTimestampAdapter类能够格外不难地分析和格式化ISO860三日期和岁月,以及HTTP
1.1
header(本田CR-VFC1123)格式。能够从https://github.com/tfredrich/DateAdapterJ下载。

  对于那么些创设基于浏览器的用户界面来说,ECMAScript5规范一发轫就富含了JavaScript解析和开创ISO860三二十一日期的始末,所以它应有成为大家所说的主流浏览器所服从的办法。当然,要是你要援助那个不可能自动解析日期的旧版浏览器,能够应用JavaStript库或正则表明式。那里有多少个能够分析和创办ISO8601时间的JavaStript库:

  http://momentjs.com/

  http://www.datejs.com/

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

  不过上述提出仅适用于HTTP请求或响应内容中的JSON和XML内容,HTTP规范针对HTTP
headers使用另一种不相同的格式。在被奥迪Q3FC1123更替的福特ExplorerFC82第22中学提议,该格式包罗了种种日期、时间和date-time格式。但是,建议始终使用时间戳格式,在您的request
headers中它看起来像这么:

  Sun, 06 Nov 1994 08:49:37 GMT

  但是,那种格式没有设想飞秒恐怕秒的十进制小数。Java的SimpleDataFormat的格式串是:”EEE,
dd MMM yyyy HH:mm:ss ‘GMT'”。

 

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

  不过上述建议仅适用于HTTP请求或响应内容中的JSON和XML内容,HTTP规范针对HTTP
headers使用另一种差别的格式。在被RAV4FC1123更替的LANDFC822中提议,该格式包含了各类日期、时间和date-time格式。可是,建议始终使用时间戳格式,在您的request
headers中它看起来像这么:

  Sun, 06 Nov 1994 08:49:37 GMT

  可是,那种格式没有考虑阿秒或然秒的十进制小数。Java的SimpleDataFormat的格式串是:”EEE,
dd MMM yyyy HH:mm:ss ‘GMT'”。

 

护卫服务的安全

  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),那么在发出远程请求前,能够在当地创造2个授权客户端来缓存最新的ACLs。

身份验证

  最近最好的做法是采取OAuth身份验证。强烈推荐OAuth2,然而它依旧居于草案情形。或许选拔OAuth1,它完全能够胜任。在好几情状下也能够挑选3-Legged
OAuth。越多关于OAuth的科班能够查阅那里http://oauth.net/documentation/spec/

  OpenID是2个外加选择。可是提出将OpenID作为二个附加的身份验证选项,以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。

授权

  对劳动的授权和对其余应用程序的授权一样,没有任何分化。它依照那样3个题材:“主体是或不是对给定的资源有请求的许可?”那里给出了大致的三项数据(主体,能源和认同),因此很简单构造多个援助那种概念的授权服务。个中大旨是被授予能源访问许可的人或系统。使用这么些相似概念,就足以为每3个大旨塑造三个缓存访问控制列表(ALC)。

授权

  对劳务的授权和对别的应用程序的授权一样,没有别的差距。它依据那样3个标题:“主体是或不是对给定的资源有请求的许可?”那里给出了简约的三项数据(主体,资源和认同),因而很简单构造一个支撑这种概念的授权服务。在那之中中央是被赋予财富访问许可的人或体系。使用那么些相似概念,就能够为每三个主题营造一个缓存访问控制列表(ALC)。

应用程序安全

  对RESTful服务以来,开发三个四平的web应用适用同样的尺度。

  • 在服务器上表明全数输入。接受“已知”的正确性的输入并驳回错误的输入。
  • 防止SQL和NoSQL注入。
  • 运用library如微软的Anti-XSS或OWASP的Anti萨姆my来对出口的数额实行编码。
  • 将新闻的长度限制在明确的字段长度内。
  • 劳动应该只突显一般的错误音信。
  • 设想工作逻辑攻击。例如,攻击者能够跳过多步骤的预购流程来预约产品而无需输入信用卡音信吗?
  • 对狐疑的运动记录日志。

  RESTful安全要求注意的地方:

  • 表达数据的JSON和XML格式。
  • HTTP动词应该被限制在同意的主意中。例如,GET请求不能够去除3个实体。GET用来读取实体而DELETE用来删除实体。
  • 小心race
    conditions(竞争原则——由于四个只怕两个经过竞争使用不能够被同时做客的能源,使得那个进度有恐怕因为时间上促进的主次原由此产出难点)。

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

  • 蹲点API的应用情形,并理解怎么着活动是常规的,哪些是非正常的。
  • 范围API的采纳,使恶意用户不能够停掉1个API服务(DOS攻击),并且有能力阻止恶意的IP地址。
  • 将API密钥存储在加密的海东密钥库中。

 

应用程序安全

  对RESTful服务来说,开发多个平安的web应用适用同样的条件。

  • 在服务器上表达全体输入。接受“已知”的没错的输入并拒绝错误的输入。
  • 防止SQL和NoSQL注入。
  • 应用library如微软的Anti-XSS或OWASP的AntiSammy来对出口的数额举办编码。
  • 将音讯的尺寸限制在分明的字段长度内。
  • 劳动应该只突显一般的错误音信。
  • 考虑工作逻辑攻击。例如,攻击者能够跳过多步骤的预购流程来预约产品而无需输入信用卡新闻呢?
  • 对思疑的活动记录日志。

  RESTful安全须求留意的地点:

  • 表明数据的JSON和XML格式。
  • HTTP动词应该被限制在允许的艺术中。例如,GET请求不可能去除一个实体。GET用来读取实体而DELETE用来删除实体。
  • 小心race
    conditions(竞争规则——由于五个可能八个经过竞争使用不可能被同时做客的能源,使得这几个经过有可能因为日子上有助于的顺序原因此出现难点)。

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

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

 

缓存和可伸缩性

  通过在系统层级解决通过中距离调用来博取请求的多寡,缓存升高了系统的可扩大性。服务通过在响应中安装headers来升高缓存的力量。遗憾的是,HTTP
1.0中与缓存相关的headers与HTTP
1.1不一,由此服务器要同时辅助三种版本。下表给出了GET请求要帮忙缓存所不可不的最少headers集合,并交给了非常的讲述。

HTTP Header

描述

示例

Date

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

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

Cache-Control

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

Cache-Control: 360

Cache-Control: no-cache

Expires

比方给出了最大age值,该时间戳(CR-VFC1123格式)表示的是响应过期的时辰,也正是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

  为了简化,那里举1个响应中的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

  下边是2个接近的例证,可是缓存被完全禁止使用:

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

缓存和可伸缩性

  通过在系统层级消除通过远程调用来获取请求的多少,缓存升高了系统的可扩展性。服务通过在响应中装置headers来进步缓存的力量。遗憾的是,HTTP
1.0中与缓存相关的headers与HTTP
1.1两样,由此服务器要同时帮忙二种版本。下表给出了GET请求要支持缓存所不可不的最少headers集合,并付诸了适度的讲述。

HTTP Header

描述

示例

Date

响应重回的日期和岁月(奇骏FC1123格式)。

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

Cache-Control

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

Cache-Control: 360

Cache-Control: no-cache

Expires

只要给出了最大age值,该时间戳(酷威FC1123格式)表示的是响应过期的时间,也正是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

能源本人最终被涂改的时刻戳(兰德RAV4FC1123格式)。

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

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)。它的值是3个任意字符串,用来代表回到数据的版本。可是,对于重临数据的不比格式,它也得以差异——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来含有1个针对最新成立的财富的链接。

  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

相关文章