RESTful服务至上实施

正文主要读者

引言

REST是什么

  集结接口

    依赖财富

    通过特征来操作财富

    自描述的消息

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

  无状态

  可缓存

  C-S架构

  分段系统

  按需编码(可选)

REST快速提醒

  利用HTTP动词表示一些意思

  创建的财富名

  XML和JSON

  始建适当粒度的能源

  考虑连通性

定义

  幂等性

  安全

HTTP动词

  GET

  PUT

  POST

  PUT和POST的创导比较

  DELETE

能源命名

  资源URI示例

  能源命名的反例

  复数

再次来到表征

  资源通过链接的可发掘性(HATEOAS续)

    小小的化链接推荐

    链接格式

  打包响应

  管理跨域难题

    支持CORS

    支持JSONP

询问,过滤和分页

  结果限制

    用范围标识实行界定

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

    据说范围的响应

  分页

  结果的过滤和排序

    过滤

    排序

劳动版本管理

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

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

  伸手不协助的版本

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

    破坏性的改变

    非破坏性的修改

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

  应用Content-Location来压实响应

  带有Content-Type的链接

  寻觅援救的本子

    自己应该而且援助多少个本子?

    弃用

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

日子/时间拍卖

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

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

保证服务的平安

  身份验证

  传输安全

  授权

  应用程序安全

缓存和可伸缩性

  ETag Header

HTTP状态码(前10)

叠合能源

  书籍

  网站

 

本文首要读者

  该最棒施行文书档案适用于对RESTful
Web服务感兴趣的开拓职员,该服务为跨四个服务的组件提供了较高的可信赖性和一致性。依照本文的点拨,可飞快、普遍、公开地为内外部客户利用。

  本文中的指点规范一致适用于技术员们,他们期待利用那一个依照最好实践标准开辟的服务。固然他们尤其爱慕缓存、代理规则、监听及安全等有关地方,然则该文书档案能作为一份包蕴全部连串服务的总指南。

  别的,通过从这个指引规范,管理职员通晓到创立公共的、提供高稳固的劳动所需成本的鼎力,他们也可从中收益。

 

引言

  现今已有多量关于RESTful
Web服务至上实施的有关资料(详见本文最终的连带文献部分)。由于撰文的光阴区别,好多资料中的内容是顶牛的。其它,想要通过翻看文献来打听这种劳动的前行是不太可取的。为了打探RESTful这一定义,至少须要查阅三到五本有关文献,而本文将可以帮您加速这一经过——吐弃多余的商量,最大化地提炼出REST的特级实践和规范。

  与其说REST是一套规范,REST更疑似一种规格的成团。除了两个第一的尺码外就不曾别的的正规了。实际上,即使有所谓的“最棒实行”和标准,但这个事物都和宗派斗争同样,在不断地演化。

  本文围绕REST的广阔难题建议了意见和仿美食做法式的座谈,并由此介绍一些大概的背景知识对成立真实景况下的预生产情形中平等的REST服务提供文化。本文搜聚了来自别的路子的音信,经历过二次次的挫败后不断创新。

  但对此REST情势是不是必然比SOAP好用仍有相当大纠纷(反之亦然),只怕在某个情状下仍必要创建SOAP服务。本文在聊起SOAP时并没有花非常大篇幅来谈谈它的争持优点。相反由于技巧和行业在不断提高,大家将一而再坚忍不拔大家的只要–REST是立即设计web服务的特级方法。

  第一部分概述REST的意义、设计准则和它的独竖一帜之处。第二有的罗列了有的小贴士来纪念REST的劳务观念。之后的一部分则会更透顶地为web服务创造人士提供一些细节的支撑和商量,来兑现一个可见公开始展览示在生养条件中的高水平REST服务。

 

REST是什么?

  REST架构格局讲述了各类设计准则。那一个用于架构的设计准则,最早是由罗伊Fielding在她的大学生故事集中建议并定义了RESTful风格。(详见http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

  五个统一计划准则分别是:

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

  以下是那几个安顿准则的事无巨细研商:

统一接口

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

  基于财富

  不相同财富需求用U福特ExplorerI来唯一标志。重临给客户端的特色和能源本人在概念上有所不一样,举例服务端不会一直传送二个数据库财富,不过,一些HTML、XML或JSON数据可见呈现部分数据库记录,如用斯拉维尼亚语来表述依然用UTF-8编码则要依靠请求和服务器完毕的内部原因来调整。

  通过特色来操作财富

  当客户端收到包罗元数据的财富的性格时,在有权力的动静下,客户端已调控的丰硕的新闻,能够对服务端的能源进行删改。

  自描述的音讯

  每条音讯都包罗充裕的数额用于确认消息该怎么管理。比如要由互联网媒体类型(已知的如MIME类型)来认可需调用哪个深入分析器。响应一样也标记了它们的缓存技术。

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

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

  除了上述内容外,HATEOS也意味着,须要的时候链接也可被含有在回去的body(或头部)中,以提供U帕杰罗I来寻找对象自己或提到对象。下文将对此举办更详细的论述。

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

无状态

  正如REST是REpresentational State
Transfer的缩写,无状态很重大。本质上,那表明了管理请求所需的意况已经包蕴在乞求小编里,也会有希望是URAV4I的一部分、查询串参数、body或底部。U昂CoraI能够唯一标志每种能源,body中也蕴藏了能源的转态(或转态改换情状)。之后,服务器将实行拍卖,将相关的图景或能源通过尾部、状态和响应body传递给客户端。

  从事大家这一行当的绝大许多人都习于旧贯使用容器来编制程序,容器中有三个“会话”的定义,用于在多少个HTTP请求下维持状态。在REST中,假使要在多个请求下保持用户情形,客户端必须回顾客户端的持有新闻来成功请求,供给时再也发送请求。自从服务端不须要保险、更新或传递会话状态后,无状态性得到了更加大的延展。其它,负载均衡器无需挂念和无状态系统里面包车型地铁对话。

  所以状态和能源间有如何差距?服务器对于状态,或然说是应用状态,所关怀的点是在当前对话或请求中要做到请求所需的数目。而财富,只怕说是资源景况,则是概念了财富特色的数额,举例存储在数据库中的数据。综上可得,应用状态是是随着客户端和伸手的改换而改造的多寡。相反,资源意况对于发出请求的客户端的话是不变的。

  在网络选择的某一特定岗位上安排贰个回去按钮,是因为它仰望您能按自然的顺序来操作吗?其实是因为它违反了无状态的规范化。有过多不信守无状态原则的案例,举个例子3-Legged
OAuth,API调用速度限制等。但要么要硬着头皮确定保障服务器中不须要在八个请求下保持利用状态。

可缓存

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

C-S架构

  统一接口使得客户端和服务端互相分开。关心分离意味什么?打个举个例子,客户端无需仓库储存数据,数据都留在服务端内部,这样使得客户端代码的可移植性获得了进级;而服务端不需求思虑用户接口和用户情状,那样一来服务端将越来越简约易拓展。只要接口不改换,服务端和客户端能够单独地展开研发和替换。

分层系统

  客户端经常不或然注解本人是直接大概直接与端服务器进行连接。中介服务器能够通过启用负载均衡或提供共享缓存来升高系统的延展性。分层时一样要思索安全计谋。

按需编码(可选)

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

  遵循上述标准,与REST架构风格保持一致,能让种种布满式超媒类别统具备梦想的自然属性,比如高质量,延展性,简洁,可变性,可视化,可移植性和可信赖性。

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

 

REST飞速提示

  (总局方提到的两个尺码)不管在工夫上是或不是RESTful的,这里有一部分看似REST概念的提议。坚守它们,能够达成更加好、更低价的劳务:

选取HTTP动词表示一些意思

  任何API的使用者能够发送GET、POST、PUT和DELETE请求,它们比极大程度分明了所给请求的指标。同时,GET请求不可能改动任何秘密的财富数量。衡量和追踪仍也许产生,但只会更新数据而不会更新由U宝马X5I标记的财富数量。

合理的财富名

  合理的财富名称或然路线(如/posts/23而不是/api?type=posts&id=23)能够更鲜喜宝个伸手的指标。使用U奥迪Q3L查询串来过滤数据是很好的点子,但不应当用于固定能源名称。

  适当的能源名字为服务端请求提供上下文,扩张服务端API的可理解性。通过U奥迪Q5I名称分层地翻看能源,能够给使用者提供一个和睦的、轻便精通的能源档次,以在她们的应用程序上运用。能源名称应当是名词,制止为动词。使用HTTP方法来钦命请求的动作部分,能让工作越来越的不可磨灭。

XML和JSON

  建议私下认可辅助json,并且,除非开支很惊人,不然就同期援助json和xml。在大好图景下,让使用者仅透过改变扩大名.xml和.json来切换类型。其它,对于支撑ajax风格的用户分界面,多少个被包裹的响应是老大有援助的。提供贰个被打包的响应,在私下认可的要么有单独扩张名的情形下,举个例子:.wjson和.wxml,声明客户端请求叁个棉被服装进的json或xml响应(请参见下边包车型大巴卷入响应)。

  “标准”中对json的渴求没多少。并且那一个需求只是语法性质的,毫无干系内容格式和布局。换句话说,REST服务端调用的json响应是说道的一部分——在正儿八经中绝非有关描述。越多关于json数据格式能够在http://www.json.org/上找到。

  关于REST服务中xml的运用,xml的正规化和预订除了选取语法准确的标签和文本外未有其他的魔法。极其地,命名空间不是也不该是被利用在REST服务端的前后文中。xml的回到更邻近于json——轻易、轻松阅读,没有方式和命名空间的细节表现——仅仅是数码和链接。即使它比那更眼花缭乱的话,参看本节的首先段——使用xml的本钱是振撼的。鉴于大家的经验,相当少有人使用xml作为响应。在它被统统淘汰以前,那是最终二个可被一定的地点。

创办适当粒度的能源

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

设想连通性

  REST的规律之一正是连通性——通过超媒体链接完成。当在响应中回到链接时,api变的更有着自描述性,而在未曾它们时服务端照旧可用。至少,接口本人可以为客户端提供怎么样搜索数据的参照。其余,在经过POST方法创立财富时,还足以行使头地方包罗贰个链接。对于响应中支持分页的汇集,”first”、
“last”、”next”、和”prev”链接至少是极其管用的。

 

定义

幂等性

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

在计算机科学中,术语幂等用于更完善地讲述一个操作,叁回或频仍实行该操作发生的结果是同样的。依据使用的上下文,那大概有两样的意思。比方,在点子或然子例程调用具备副成效的情景下,意味着在首先调用之后被修改的动静也维持不变。

  从REST服务端的角度来看,由于操作(或服务端调用)是幂等的,客户端能够用重新的调用而产生一样的结果——在编制程序语言中操作疑似二个”setter”(设置)方法。换句话说,便是应用三个一样的伸手与行使单个请求效果等同。注意,当幂等操作在服务器上发出同样的结果(副成效),响应自个儿也许是见仁见智的(举个例子在三个请求之间,能源的景色也许会转移)。

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

安全

  来自维基百科:

局地措施(比如GET、HEAD、OPTIONS和TRACE)被定义为安全的章程,那意味着它们仅被用来消息搜索,而无法改造服务器的状态。换句话说,它们不会有副成效,除了相对来讲无毒的熏陶如日志、缓存、横幅广告或计数服务等。任性的GET请求,不思量选拔状态的上下文,都被以为是平安的。

  综上说述,安全意味着调用的不二秘诀不会挑起副作用。由此,客户端能够频仍使用安全的呼吁而不用忧虑对服务端爆发任何副效能。那意味服务端必须信守GET、HEAD、OPTIONS和TRACE操作的平安概念。不然,除了对消费端发生模糊外,它还有恐怕会形成Web缓存,寻觅引擎以及任何活动代理的主题素材——那将要服务器上发生意料之外的后果。

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

  安全的点子被达成为只读操作。然则,安全并不意味着服务器必须每回都回来同样的响应。

 

HTTP动词

  Http动词首要服从“统一接口”规则,并提须要我们相应的基于名词的能源的动作。最要紧依然最常用的http动词(或然叫做方法,那样称呼也许更安妥些)有POST、GET、PUT和DELETE。这几个分别对应于成立、读取、更新和删除(CRUD)操作。也会有大多别的的动词,不过利用效用好低。在这一个使用较少的艺术中,OPTIONS和HEAD往往采用得更加多。

GET

  HTTP的GET方法用于检索(或读取)财富的数码。在科学的呼吁路线下,GET方法会再次来到一个xml恐怕json格式的多少,以及壹个200的HTTP响应代码(表示正确重临结果)。在错误景况下,它一般重临404(不存在)或400(错误的伏乞)。

  例如:

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

  遵照HTTP的设计标准,GET(以及附带的HEAD)请求仅用于读取数据而不转移多少。因而,这种利用格局被感到是高枕而卧的。也等于说,它们的调用未有数量修改或污染的高危害——调用1次和调用14回依然没有被调用的法力等同。其它,GET(以及HEAD)是幂等的,那意味着使用四个同样的请求与使用单个的请求最后都有着同样的结果。

  不要通过GET暴光不安全的操作——它应当长久都不能够改改服务器上的任何财富。

PUT

  PUT常常被用于立异财富。通过PUT请求一个已知的财富U卡宴I时,要求在呼吁的body中包涵对原来财富的翻新数据。

  不过,在能源ID是由客服端而非服务端提供的气象下,PUT一样能够被用来创建财富。换句话说,假设PUT请求的U本田UR-VI中隐含的财富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。

POST

  POST请求平日被用于创制新的能源,非常是被用来创设从属财富。从属能源即归属于别的财富(如父能源)的能源。换句话说,当创立八个新能源时,POST请求发送给父能源,服务端担负将新财富与父财富举办关联,并分配贰个ID(新财富的U科雷傲I),等等。

  例如:

  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:即纵然客户端知道U君越I(或能源ID)是如何,则对该UMuranoI使用PUT请求。不然,当由服务器或服务端来支配创造的财富的UGL450I时则选拔POST请求。换句话说,当客户端在开创在此之前不精通(或不或者清楚)结果的U科雷傲I时,使用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(未找到)。

 

能源命名

  除了适本地使用HTTP动词,在成立叁个得以领略的、易于使用的Web服务API时,财富命名能够说是最具有争商谈最重大的概念。多个好的财富命名,它所对应的API看起来更加直观并且易于使用。相反,如若命名不佳,同样的API会让人以为很拙笨并且难以知晓和接纳。当您供给为你的新API创制能源U卡宴L时,这里有局地小技术值得借鉴。

  从实质上讲,三个RESTFul
API最终都能够被归纳地作为是一批U安德拉I的晤面,HTTP调用那一个U本田CR-VI以及一些用JSON和(或)XML表示的财富,它们中有大多蕴含了交互关系的链接。RESTful的可寻址工夫根本依赖U奥迪Q5I。每一个能源都有和好的地点或U福睿斯I——服务器能提供的每三个卓有成效的新闻都得以当做财富来公开。统一接口的标准部分地由此U逍客I和HTTP动词的三结合来化解,并符合利用标准和平条目款项定。

  在决定你系统中要选用的财富时,使用名词来命名那一个能源,而不是用动词或动作来定名。换句话说,一个RESTful
UOdysseyI应该提到到三个有血有肉的财富,而不是事关到贰个动作。其它,名词还具备部分动词未有的性质,那也是另贰个明确的要素。

  一些财富的例子:

  • 系统的用户
  • 学员注册的课程
  • 三个用户帖子的时辰轴
  • 关怀别的用户的用户
  • 一篇有关骑马的篇章

  服务套件中的每种能源最少有三个UGL450I来标记。若是这些UOdysseyI能表示一定的意义并且能够丰盛描述它所代表的财富,那么它就是一个最佳的命名。U奥迪Q3I应该具有可预测性和分层结构,那将推进增加它们的可驾驭性和可用性的:可预测指的是能源应该和称号保持一致;而分层指的是数码颇具关系上的构造。那并非REST规则或标准,不过它加重了对API的定义。

  RESTful
API是提要求消费端的。U大切诺基I的称谓和布局应当将它所抒发的意义传达给顾客。日常大家很难理解多少的界线是何许,但是从您的数目上你应有很有很大希望去品尝找到要回到给客户端的数码是如何。API是为客户端而规划的,而不是为你的多少。

  假使我们前几天要描述二个归纳客户、订单,列表项,产品等功用的订单系统。考虑一下大家该怎么着来描述在那么些服务中所涉及到的财富的U昂科拉Is:

资源URI示例

  为了在系统中插入(创制)贰个新的用户,咱们得以选用:

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

 

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

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

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

 

  上面是对成品有关的U本田CR-VI的局地建议:

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

  用于创立新的成品。

 

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

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

 

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

  一种方案是:

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

  这种方式能够用来成立订单,但缺少相应的用户数据。

  

  因为大家想为用户创造二个订单(注意之间的关系),这些UEnclaveI可能非常不够直观,下边那些USportageI则更清晰一些:

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

  未来大家清楚它是为编号33245的用户成立三个订单。

 

  那上边那么些请求重返的是怎么吧?

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

  可能是一个数码为33245的用户所创办或富有的订单列表。注意:大家得以屏蔽对该UCRUISERI实行DELETE或PUT请求,因为它的操作对象是五个汇聚。

 

  继续长远,那下边那么些U奥迪Q5I的呼吁又表示怎样呢?

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

  也许是(为编号33245的用户)扩充三个数码为8769的订单条约。没有错!假若利用GET方式呼吁这一个U奥迪Q3I,则会回到那个订单的具备条条框框。不过,要是这一个条目与用户音讯非亲非故,我们将会提供POST
www.example.com/orders/8769/lineitems
这个URI。

  从重临的那些条约来看,钦定的财富大概会有多少个UTucsonIs,所以大家只怕也亟供给提供这么三个U福睿斯I
GET
http://www.example.com/orders/8769
,用来在不晓得用户ID的情形下基于订单ID来询问订单。

 

  更进一步:

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

  也许只回去同个订单中的第一个条约。

  将来您应该明白什么是分层结构了。它们并不是严刻的平整,只是为着确定保障在你的劳务中那么些强制的布局能够更便于被用户所知晓。与持有软件开采中的本领同样,命名是打响的根本。

  

  多看有个别API的亲自过问并学会控制那个本领,和你的队友一齐来完善你API财富的U宝马7系Is。这里有一部分APIs的例证:

能源命名的反例

  前面大家曾经切磋过部分合适的能源命名的事例,可是一时一些反面包车型客车例子也很有教育意义。上面是有的不太具有RESTful风格的财富U帕杰罗Is,看起来对比散乱。这个都是漏洞百出的例子! 

  首先,一些serivices往往选择单一的U陆风X8I来钦赐服务接口,然后通过查询参数来钦点HTTP请求的动作。举例,要创新编号12345的用户消息,带有JSON
body的恳求只怕是如此:

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

  就算地点U路虎极光L中的”services”的这一个节点是三个名词,但这几个U奥迪Q3L不是自解释的,因为对此持有的请求来说,该UCR-VI的层级结构都以一律的。其余,它利用GET作为HTTP动词来试行三个更新操作,那简直正是反人类(乃至是危险的)。

  上边是其它三个革新用户的操作的事例:

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

  以及它的三个变种:

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

  你会时常看看在别的开采者的劳务套件中有那一个如此的用法。能够见见,这几个开垦者试图去创制RESTful的能源名称,而且已经有了一些迈入。可是你如故能够辨识出U昂CoraL中的动词短语。注意,在这些ULX570L中我们无需”update”这一个词,因为大家得以借助HTTP动词来产生操作。上边那么些U奥德赛L正好表达了那或多或少:

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

  这么些请求同期设有PUT和”update”,那会对消费者爆发吸引!这里的”update”指的是多个能源吗?由此,这里大家费些口舌也是梦想你能够驾驭……

复数

  让大家来研讨一下复数和“单数”的争执…还没听别人讲过?但这种争论确实存在,事实上它可以归纳为那几个主题材料……

  在您的层级结构中U君越I节点是还是不是须要被命名称为单数或复数情势呢?举个例证,你用来寻觅用户财富的ULacrosseI的命名是或不是必要像上边那样:

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

  或者:

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

  两种艺术都没难题,但普通大家都会挑选选用复数命名,以使得你的API
U大切诺基I在具有的HTTP方法中保持一致。原因是基于那样一种思虑:customers是劳动套件中的叁个会集,而ID33245的那么些用户则是以此集合中的个中一个。

  依据这些规则,三个选取复数格局的多节点的UENVISIONI会是那样(注意粗体部分):

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

  “customers”、“orders”以及“lineitems”那一个U中华VI节点都利用的是复数格局。

  那意味着你的每种根财富只须求三个大旨的UCR-VL就能够了,多个用以创立集合内的能源,另三个用来依据标志符获取、更新和删除财富。举个例子,以customers为例,创造能源得以行使下边包车型地铁ULX570L进行操作:

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

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

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

  正如前方提到的,给定的财富只怕有多少个URAV4I,但作为一个小小的的完全的增加和删除改查功效,利用三个简单的USportageI来拍卖就够了。

  也许你会问:是还是不是在有个别意况下复数未有趣?嗯,事实上是那般的。当未有集结概念的时候(此时复数没风趣)。换句话说,当财富唯有三个的状态下,使用单数财富名称也是可以的——即一个单一的财富。举例,假使有一个纯粹的完全布局能源,你能够行使多个单数名称来代表:

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

  注意这里贫乏configuration的ID以及HTTP动词POST的用法。假设各种用户有一个布置来讲,那么这些U昂科威L会是那般:

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

  同样让人瞩目这里没有一点点名configuration的ID,以及未有给定POST动词的用法。在那多个例证中,大概也是有人认为利用POST是有效的。好吧…

 

回去表征

  正如前方提到的,RESTful接口扶助种种能源特点,包罗JSON和XML,以及被打包的JSON和XML。建议JSON作为默许表征,可是服务端应该允许客户端钦定别的表征。

  对于客户端请求的特色格式,我们可以在Accept头通过文件扩充名来张开点名,也足以通过query-string等任何方法来钦点。理想状态下,服务端能够支撑具备这几个方式。可是,现在正式更赞成于通过类似于文件增添名的方法来开始展览点名。因而,建议服务端至少需求援助使用文件扩充名的办法,举例“.json”,“.xml”以及它们的包裹版本“.wjon”,“.wxml”。

  通过这种方法,在U大切诺基I中钦命再次来到表征的格式,能够抓实UPRADOL的可知性。比方,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头,服务端要同有的时候候扶助封装和未封装的响应,你不能不兑现自定义的门类——因为那个格式不是标准的项目。那大大扩展了客户端和服务端的千头万绪。请参见OdysseyFC
2616的14.1节关于Accept头的详细音信(http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1)。使用文件扩大名来内定数量格式是最轻易易行直接的法子,用最少的字符就能够达成,并且接济脚本操作——不要求利用HTTP头。

  平常当大家关系REST服务,跟XML是无关的。固然服务端帮忙XML,也大概从不人提出在REST中利用XML。XML的正式和公约在REST中不太适用。极其是它连命名空间都未有,就更不应当在RESTful服务连串中运用了。那只会使业务变得更目迷五色。所以回来的XML看起来更像JSON,它总结易读,未有情势和命名空间的界定,换句话来讲是无规范的,易于剖析。

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

  REST教导规范之一(依照统一接口标准)是application的图景通过hypertext(超文本)来传输。那正是大家普通所说的Hypertext
As The Engine of Application State
(即HATEOAS,用超文本来作为应用程序状态机),我们在“REST是什么”一节中也事关过。

  遵照罗伊Fielding在他的博客中的描述(http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertextdriven),REST接口中最根本的一部分是超文本的行使。其余,他还建议,在付出任何有关的新闻以前,贰个API应该是可用和可精通的。也等于说,贰个API应当能够经过其链接导航到多少的顺序部分。不提出只回去纯数据。

  但是当下的产业界先驱们并不曾平时利用这种做法,这呈现了HATEOAS仅仅在成熟度模型中的使用率更加高。纵观者多的服务种类,它们多数再次来到越来越多的多寡,而回到的链接却没多少(可能尚未)。那是违背Fielding的REST约定的。菲尔德ing说:“音讯的每多少个可寻址单元都指导三个地点……查询结果应该展现为三个包蕴摘要音讯的链接清单,而不是指标数组。”

  另一方面,轻松狠毒地将全体链接集合再次来到会大大影响互联网带宽。在事实上景况中,依据所需的标准化或使用景况,API接口的通讯量要凭借服务器响应中中国足球球组织拔尖联赛文本链接所包含的“摘要”数量来抵消。

  同有的时候间,丰富利用HATEOAS大概会追加达成的纷纷,并对劳动客户端产生显著的担当,这一定于降低了客户端和服务器端开荒职员的生产力。由此,当劳之急是要平衡超链接服务实行和水保可用财富之间的主题素材。

  超链接最小化的做法是在最大限度地回落客户端和服务器之间的耦合的相同的时候,进步服务端的可用性、可垄断(monopoly)性和可明白性。那几个最小化建议是:通过POST创设财富并从GET请求重临集结,对于有分页的景况后边我们会提到。

小小的化链接推荐

  在create的用例中,新建财富的U大切诺基I(链接)应该在Location响应头中回到,且响应中央是空的——大概只含有新建财富的ID。

  对于从服务端重回的特征会集,每一种表征应该在它的链接群集中教导一个微细的“自个儿”链接属性。为了方便分页操作,此外的链接能够投身一个独自的链接群集中回到,须要时方可涵盖“第一页”、“上一页”、“下一页”、“最终一页”等音信。

  参照下文链接格式一对的例子获取越来越多音信。

链接格式

  参照整个链接格式的标准,提出服从一些近似Atom、AtomPub或Xlink的风骨。JSON-LD也没有错,但并未被广泛使用(要是已经被用过)。近年来正式最常见的艺术是采纳带有”rel”成分和包括财富全体U福特ExplorerI的”href”成分的Atom链接格式,不带有其余身份验证或询问字符串参数。”rel”成分得以涵盖标准值”alternate”、”related”、”self”、”enclosure”和”via”,还会有分页链接的“第一页”、“上一页”、“下一页”,“最终一页”。在须求时方可自定义并丰富应用它们。

  一些XML
Atom格式的概念对于用JSON格式表示的链接来讲是行不通的。比如,METHOD属性对于多少个RESTful财富来讲是不供给的,因为对于二个加以的能源,在有着帮衬的HTTP方法(CRUD行为)中,财富的U卡宴I都以同一的——所以单独列出那一个是不曾要求的。

  让我们举一些现实的例子来特别验证这点。下边是调用创立新能源的伏乞后的响应:

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

  上边是响应头集合中包涵创立新财富的U牧马人I的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响应(每页呈现3项),大家提交第三页的数额:

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

  在这几个例子中,响应中用来分页的links会集中的每一项都包蕴三个对准“自己(self)”的链接。这里只怕还应该有部分事关到集中的其余链接,但都与分页本人无关。简单的说,这里有七个地点含有links。多少个正是data对象中所包蕴的集聚(那一个也是接口要赶回给客户端的数额表征集结),个中的各样至少要包含一个针对性“本身(self)”的links集合;另一个则是一个单独的对象links,个中囊括和分页相关的链接,该有的的剧情适用于全部集结。

  对于经过POST请求成立能源的处境,必要在响应头中包括二个事关新建对象链接的Location

包装响应

   服务器能够在响应中并且重返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和跨域财富共享(COPRADOS)。JSONP或“填充的JSON”是一种选用格局,它提供了叁个办法请求来自分化域中的服务器的多寡。其职业格局是从服务器重临任性的JavaScript代码,而不是JSON。客户端的响应由JavaScript解析器举办解析,而不是直接分析JSON数据。别的,COTucsonS是一种web浏览器的本领职业,它为web服务器定义了一种艺术,从而允许服务器的财富得以被不一样域的网页访问。CO奥迪Q3S被当做是JSONP的新式代替品,并且能够被全体今世浏览器帮忙。因而,不提议选拔JSONP。任何意况下,推荐采纳COOdysseyS。

支持CORS

  在服务端完毕CO奥迪Q5S很简短,只供给在发送响应时顺手HTTP头,举个例子: 

Access-Control-Allow-Origin: *

  唯有在数额是公物使用的情状下才会将访问来源设置为”*”。大多数场地下,Access-Control-Allow-Origin头应该钦定哪些域能够发起一个CORAV4S请求。唯有供给跨域访问的UENCOREL才设置COWranglerS头。

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

  以上Access-Control-Allow-Origin头中,被安装为只同意受信赖的域能够访问。

Access-Control-Allow-Credentials: true

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

  这么些headers能够由此web服务器、代理来进展布署,大概从服务器自己发送。不引入在服务端完毕,因为很不利索。也许,可以动用方面包车型大巴第三种方式,在web服务器上布署四个用空格分隔的域的列表。越来越多关于CO瑞鹰S的剧情能够参照这里:http://enable-cors.org/

支持JSONP

  JSONP通过动用GET请求避开浏览器的限量,从而完毕对拥有服务的调用。其行事规律是请求方在伸手的U奥迪Q3L上增多一个字符串查询参数(举个例子:jsonp=”jsonp_callback”),当中“jsonp”参数的值是JavaScript函数名,该函数在有响应再次来到时将会被调用。

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

  JSONP平日在局部不援救CO瑞虎S的老旧浏览器中利用,就算要改成帮忙COSportageS的,会潜移默化总体服务器的架构。可能大家也能够通过代办来兑现JSONP。由此可见,JSONP正在被COQashqaiS所代表,咱们相应尽量地动用CO卡宴S。

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

  1. 响应体必须封装成叁个参数传递给jsonp中钦点的JavaScript函数(比如:jsonp_callback(“<JSON
    response body>”))。
  2. 一味重临HTTP状态码200(OK),并且将真正的动静作为JSON响应中的一某些再次来到。

  别的,响应体中通常必须带有响应头。那使得JSONP回调方法必要基于响应体来规定响应处理情势,因为它本身不只怕获悉真实的响应头和情景值。

  下边包车型地铁例证是依照上述情势封装的壹个赶回error状态的jsonp(注意:HTTP的响应状态是200):

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

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

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

 

询问,过滤和分页

  对于大数据集,从带宽的角度来看,限制重回的数据量是不行关键的。而从UI管理的角度来看,限制数据量也一如在此以前至关心重视要,因为UI常常只可以突显大数目汇总的一小部分数额。在数据集的增速不明显的景况下,限制暗中认可再次来到的数据量是很有必不可缺的。以推特(TWTR.US)为例,要博得有些用户的推文(通过个人主页的光阴轴),借使未有非常内定,请求默许只会回去20条记下,即使系统最多能够回到200条记下。

  除了限制重临的数据量,大家还亟需思虑怎样对命局据集实行“分页”或下拉滚动操作。创造数量的“页码”,再次来到大数目列表的已知片段,然后标出数据的“前一页”和“后一页”——这一表现被叫作分页。别的,大家只怕也亟需钦赐响应中校包涵哪些字段或质量,从而限制重返值的数据,并且我们盼望最终能够透过一定值来张开查询操作,并对再次来到值举行排序。

  有三种首要的方式来还要限制查询结果和施行分页操作。首先,大家得以创制二个目录方案,它可以以页码为导向(请求中要交给每一页的记录数及页码),也许以记录为导向(请求中中央银行政机关接提交第一条记下和最后一条记下)来规定再次回到值的原初地方。例如,那三种格局分别代表:“给出第五页(若是每页有20条记下)的记录”,或“给出第100到第120条的笔录”。

  服务端将依赖运作机制来开始展览切分。有个别UI工具,比方Dojo
JSON会选拔模仿HTTP规范行使字节范围。若是服务端帮助out of
box(即开箱即用效应),则前端UI工具和后端服务时期没有要求任何转换,那样使用起来会很有益于。

  下文将介绍一种艺术,既可以够支持Dojo那样的分页格局(在请求头中付出记录的限制),也能支持使用字符串查询参数。那样一来服务端将变得进一步灵敏,不只能够动用类似Dojo同样先进的UI工具集,也足以选用简便直接的链接和标签,而不供给再为此扩展复杂的支付专业。但若是服务不直接帮忙UI成效,能够设想不要在请求头中付出记录范围。

  要极其建议的是,大家并不引入在具备服务中利用查询、过滤和分页操作。并不是具备财富都暗许辅助这个操作,唯有有些特定的财富才支撑。服务和能源的文书档案应当表达怎么样接口扶助这一个纷纷的效用。

结果限制

  “给出第3到第55条的笔录”,这种请求数据的措施和HTTP的字节范围标准更平等,由此大家得以用它来标志Range
header。而“从第2条记下开端,给出最多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起先算起。上述的乞求将会回到前贰十五个记录,要是数据汇总至少有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值,可是这么些参数的应用都急需在文书档案中展开求证。

听别人讲范围的响应

  对叁个根据范围的伸手来说,无论是通过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

  在大部气象下,这种分页方式都尚未难点。但不常会有这种气象,正是要再次来到的笔录数据不能直接表示成多少汇总的行号。还或者有就是某些数据集的生成相当慢,不断会有新的数额插入到多少聚集,那样自然会产生分页出现难题,一些双重的数量或然会现出在分裂的页中。

  按日期排列的数据集(举个例子推文(Tweet)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等相结合,能够达成庞大的数据检索功效。

  再重申一回,过滤和排序都以错综相连的操作,无需暗许提须要具有的能源。下文将介绍怎么着能源供给提供过滤和排序。

过滤

  在本文中,过滤被定义为“通过特定的规格来明确必须求赶回的数目,从而缩小重临的数码”。即使服务端帮衬一套完整的可比运算符和千头万绪的准绳协作,过滤操作将变得一定复杂。可是大家普通会采用一些粗略的表明式,如starts-with(以…起头)或contains(包括)来开始展览相称,以确认保障重临数据的完整性。

  在大家初阶探讨过滤的字符串查询参数此前,必须先明了怎么要选取单个参数而不是两个字符串查询参数。从根本上来讲是为着削减参数名称的争辩。我们已经有offsetlimitsort(见下文)参数了。假如只怕的话还应该有jsonpformat标志符,恐怕还或者有afterbefore参数,这几个都是在本文中涉嫌过的字符串查询参数。字符串查询中使用的参数越多,就越恐怕导致参数名称的争执,而采取单个过滤参数则会将冲突的可能性降到最低。

  别的,从服务端也很轻便仅通过单个的filter参数来判定请求方是不是必要多少过滤效果。假若查询需求的复杂度扩张,单个参数将更富有灵活性——能够协和树立一套成效一体化的查询语法(详见下文OData注释或访问http://www.odata.org)。

  通过引进一组广泛的、公认的分隔符,用于过滤的说明式能够以十三分直观的情势被采纳。用这一个分隔符来设置过滤查询参数的值,那一个分隔符所创造的参数名/值对能够越发轻便地棉被和衣服务端解析并抓实数据查询的性格。最近已部分分隔符蕴含用来分隔各类过滤短语的竖线(”|”)和用来分隔参数名和值的双冒号(”::”)。那套分隔符丰富唯一,并符合大好多意况,同期用它来创设的字符串查询参数也特别便于通晓。上面将用三个简短的例子来介绍它的用法。如果我们想要给名叫“Todd”的用户们发送请求,他们住在突温尼伯城,有着“Grand
Poobah”之称。用字符串查询参数完结的呼吁U陆风X8I如下:

  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

  再一次重申一下,查询参数名/值对中的属性名要和服务端重临的属性名相相配。其它,由于排序操作相比复杂,大家只对急需的财富提供排序功用。假设必要的话也能够在客户端对小的财富聚集进行排列。

 

劳动版本管理

   爽直地讲,一谈起版本就能令人以为很辛苦,很劳累,不太轻易,甚至会让人觉着难熬——因为那会增添API的复杂度,并同时大概会对客户端发生一些影响。因而,在API的妄想中要尽量幸免多个不等的版本。

  不协助版本,不将版本调控作为不佳的API设计的注重。要是您在APIs的规划中引进版本,那迟早都会让您抓狂。由于重回的多少通过JSON来显现,客户端会由于不一致的版本而接受到分化的属性。这样就能存在部分标题,如从内容自己和表达规则方面改造了五个已存在的属性的意思。

  当然,我们鞭长莫及幸免API大概在有个别时候要求更换再次来到数据的格式和剧情,而这也将促成消费端的一对更改,我们相应幸免进行一些首要的调动。将API进行版本化管理是幸免这种重大变动的一种有效方式。

通过情节协商辅助版本管理

  未来,版本管理通过UHighlanderI本人的版本号来实现,客户端在呼吁的U途乐I中标注要收获的能源的版本号。事实上,许多大公司如Facebook、Yammer、Instagram、谷歌(Google)等不经常在他们的UQashqaiI里使用版本号。以至像WSO2那样的API处理工具也会在它的U汉兰达Ls中需要版本号。

  面向REST原则,版本管理技艺飞快发展。因为它不含有HTTP规范中置放的header,也不帮忙仅当四个新的财富或概念被引进时才应该增多新UOdysseyI的见地——即版本不是表现情势的改动。另三位歌唱会对台戏的说辞是能源U中华VI是不会随时间改造的,财富正是资源。

  U大切诺基I应该能大约地识别能源——而不是它的“形状”(状态)。另三个便是必须内定响应的格式(表征)。还应该有局地HTTP
headers:Accept 和 Content-Type。Accept
header允许客户端钦命所企望或能扶助的响应的传播媒介类型(一种或三种)。Content-Type
header可分别被客户端和劳动端用来钦命请求或响应的数据格式。

  举个例子,要拿走一个user的JSON格式的数据:

  #Request:

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

  #Response:

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

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

  以往,我们对同样能源请求版本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被用来代表所愿意的响应格式(以及示例中的版本号),注意上述四个同样的UEscortI是哪些成功在分裂的本子中分辨能源的。可能,倘诺客户端须求八个XML格式的多寡,能够将Accept
header设置为”application/xml”,即使须要的话也足以带三个点名的版本号。

  由于Accept
header能够被设置为允许三种媒体类型,在响应请求时,服务器将把响应的Content-Type
header设置为最相配客户端请求内容的种类。更加多音讯方可参照http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.Html

  例如:

  #Request

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

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

  上述呼吁中,借使服务器帮衬JSON
和XML格式的伸手,也许二种都支持,那么将由服务器来决定最后回到哪连串型的数据。但随意服务器选拔哪类,都会在响应中带有Content-Type
header。

  举个例子,借使服务器重回application/xml格式的数据,结果是:

  #Response

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

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

  为了求证Content-Type在发送数据给服务器时的用处,这里给出三个用JSON格式创设新用户的例证:

  #Request

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

  {“name”:”Marco Polo”}

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

  #Request

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

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

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

  并无需在每五个呼吁中都钦命版本号。由于HTTP
content-negotiation(内容协商)服从类型的“最棒相称”方式,所以您的API也应有依照那点。遵照这一原则,当客户端从未点名版本时,API应当再次来到所支撑的最早版本。

  照旧这些事例,获取叁个user的JSON格式的数目:

  #Request

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

  #Response

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

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

  相应地,当以POST方式向服务器发送数据时,假设服务器援救两个例外版本,而请求时又尚未点名版本,和上边的例证一样——服务器会将小小/最早版本的多寡包涵在body中。为了举办验证,上边包车型大巴事例以JSON格式请求一个带有多版本财富的服务器,来成立叁个新用户(预期会再次回到版本1):

  #Request

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

  {“name”:”Marco Polo”}

  #Response

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

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

请求不援救的本子

  当呼吁一个不匡助的本子号时(包括在API生命周期中曾经熄灭的财富版本),API应当重回贰个荒唐的HTTP状态码406(表示不被接受)。别的,API还相应再次来到四个暗含Content-Type:
application/json的响应体,在那之中带有三个JSON数组,用于注脚该服务器协助的连串。

  #Request

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

  #Response

  HTTP/1.1 406 NOT ACCEPTABLE 

  Content-Type: application/json

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

怎么着时候应该创制叁个新本子?

  API开辟中的许多上边都会打破约定,并最终对客户端产生部分不良影响。假若您不鲜明API的修改会带来什么样的结局,保证起见最佳挂念使用版本调控。当您在缅想提供三个新本子是不是适用时,也许思考对现存的回来表征举办改动是还是不是料定能满意急需并被客户端所收受时,有诸如此类多少个成分要思量。

破坏性的退换

  • 退换属性名(比如将”name”改成”firstName”)
  • 删除属性
  • 转移属性的数据类型(比如将numeric变为string,
    boolean变为bit/numeric,string 变为 datetime等等)
  • 退换验证规则
  • 新普京娱乐场,在Atom样式的链接中,修改”rel”的值
  • 在现成的职业流中引进须求财富
  • 转移能源的概念/意图;概念/意图或财富气象的含义分歧于它原有的意义。举例:
    • 三个content
      type是text/html的财富,此前表示的是有所协理的传播媒介类型的一个”links”集合,而新的text/html则代表的是用户输入的“web浏览器表单”。
    • 叁个富含”endTime”参数的API,对能源”…/users/{id}/exams/{id}”表达的含义是学员在特别时间付诸试卷,而新的意思则是试验的预约达成时间。
  • 经过增加新的字段来改造现存的财富。将七个财富集结为叁个并弃用原始的财富。
    • 有如此四个财富”…/users/{id}/dropboxBaskets/{id}/messages/{id}”和”…/users/{id}/dropboxBaskets/{id}/messages/{id}/readStatus”。新需借使把readStatus财富的性质放到单独的message能源中,并弃用readStatus能源。那将招致messages能源中指向readStatus能源的链接被移除。

  就算下面列出的并不周全,但它交给了有的会对客户端爆发破坏性影响的变动类型,那时须要思虑提供贰个新能源或新本子。

非破坏性的更换

  • 在重返的JSON中加多新属性
  • 增加指向任何财富的”link”
  • 增添content-type协助的新格式
  • 增添content-language扶助的新格式
  • 鉴于API的创造者和买主都要拍卖不一致的casing,因而casing的浮动非亲非故首要

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

  建议对单个的能源拓展版本调整。对API的某个改成,如修改职业流,只怕要跨五个能源的版本调控,以此来防止对客户端发生破坏性的震慑。

行使Content-Location来拉长响应

  可选。见TucsonDF(Resource Description Framework,即能源描述框架)标准。

带有Content-Type的链接

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

找寻帮助的版本

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

  维护两个分裂的版本会让职业变得繁琐、复杂、轻松出错,而且代价高,对于别的给定的能源,你应有帮衬不超过2个本子。

弃用

  Deprecated(弃用)的目标是用来证实能源对API依然可用,但在前日会不存在并变得不可用。留意:弃用的时间长度将由弃用政策决定——这里并未交到定义。

小编哪些告知客户端被弃用的能源?

  多数客户端以后走访的财富恐怕在新本子引入后会被屏弃掉,由此,他们需求有一种办法来发掘和监督他们的应用程序对弃用财富的行使。当呼吁二个弃用财富时,API应该健康响应,并含有二个布尔类型的自定义Header
“Deprecated”。以下用三个例证来张开表明。

  #Request

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

  #Response

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

 

日期/时间拍卖

  如果未有安妥地、一致地管理好日期和岁月以来,这将变为三个大麻烦。大家常常会遇见时区的标题,而且由于日期在JSON中是以字符串的格式存在的,假诺未钦点统一的格式,那么剖判日期也会是二个主题素材。

  在接口内部,服务端应该以UTC或螺旋霉素T时间来存款和储蓄、管理和缓存时间戳。那将有效化解日期和岁月的题目。

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

  有三个轻便易行的办法能够消除那一个主题材料——在字符串中始终用同样的格式,包蕴时间片(带临时区新闻)。ISO8601时间格式是贰个没有错的消除方案,它接纳了完全巩固的年华格式,包含小时、分钟、秒以及秒的小数部分(比如yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)。建议在REST服务的body内容中(请求和响应均蕴含)使用ISO8601代表享有的日子格式。

  顺便提一下,对于那么些基于JAVA的服务以来,DateAdapterJ库使用DateAdapter,Iso8601TimepointAdapter和HttpHeaderTimestamp艾达pter类能够特别轻松地剖判和格式化ISO8601日期和岁月,以及HTTP
1.1
header(PAJEROFC1123)格式。能够从https://github.com/tfredrich/DateAdapterJ下载。

  对于那么些成立基于浏览器的用户分界面来讲,ECMAScript5专门的学问一同头就隐含了JavaScript分析和创设ISO8601日期的内容,所以它应该成为我们所说的主流浏览器所遵守的法门。当然,假使你要扶助那多少个不能自动深入分析日期的旧版浏览器,能够选拔JavaStript库或正则表明式。这里有多少个能够深入分析和开创ISO8601时间的JavaStript库:

  http://momentjs.com/

  http://www.datejs.com/

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

  然则上述提出仅适用于HTTP请求或响应内容中的JSON和XML内容,HTTP规范针对HTTP
headers使用另一种差别的格式。在被RubiconFC1123更替的君越FC822中提议,该格式包含了种种日期、时间和date-time格式。可是,提出始终使用时间戳格式,在你的request
headers中它看起来像那样:

  Sun, 06 Nov 1994 08:49:37 GMT

  可是,这种格式未有思索纳秒大概秒的十进制小数。Java的SimpleDataFormat的格式串是:”EEE,
dd MMM yyyy HH:mm:ss ‘达托霉素T'”。

 

保卫安全服务的三门峡

  Authentication(居民身份证明)指的是承认给定的呼吁是从服务已知的某人(或有些系统)发出的,且请求者是他和煦所表明的特外人。Authentication是为着证实请求者的诚实身份,而authorization(授权)是为着验证请求者有权力去推行被呼吁的操作。

  本质上,那个进度是那般的:

  1. 客户端发起贰个请求,将authentication的token(身份验证令牌)包涵在X-Authentication
    header中,或者将token外加在伏乞的查询串参数中。
  2. 服务器对authorization
    token(授权令牌)实行检讨,并举办验证(有效且未过期),并基于令牌内容解析大概加载认证主题。
  3. 服务器调用授权服务,提供验证焦点、被呼吁财富和须求的操作许可。
  4. 比如授权通过了,服务器将会几次三番健康运作。

  上边第三步的花费可能会十分的大,不过假如如若存在三个可缓存的权柄调整列表(ACL),那么在发出远程请求前,能够在地面成立八个授权客户端来缓存最新的ACLs。

身份验证

  近来最佳的做法是运用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。

授权

  对劳动的授权和对任何应用程序的授权同样,未有别的不相同。它依据那样一个主题素材:“主体是或不是对给定的资源有请求的许可?”这里给出了简短的三项数据(主体,财富和认同),因而很轻巧构造三个支撑这种概念的授权服务。在那之中主旨是被授予能源访问许可的人或种类。使用那个相似概念,就可以为每三个核心营造二个缓存访问调控列表(ALC)。

应用程序安全

  对RESTful服务来讲,开荒贰个安全的web应用适用同样的规格。

  • 在服务器上印证全数输入。接受“已知”的精确性的输入并驳回错误的输入。
  • 防止SQL和NoSQL注入。
  • 运用library如微软的Anti-XSS或OWASP的AntiSammy来对出口的数码开始展览编码。
  • 将音信的长短限制在规定的字段长度内。
  • 劳务应该只突显一般的错误音讯。
  • 思索工作逻辑攻击。比如,攻击者可以跳过多步骤的预约流程来预约产品而没有供给输入信用卡新闻吗?
  • 对疑惑的运动记录日志。

  RESTful安全要求留意的地点:

  • 说明数据的JSON和XML格式。
  • HTTP动词应该被限制在允许的法子中。比方,GET请求无法去除一个实体。GET用来读取实体而DELETE用来删除实体。
  • 注意race
    conditions(竞争条件——由于四个或许多个经过竞争使用不可能被同期做客的能源,使得那个经过有希望因为日子上助长的先后原由此现身难点)。

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

  • 蹲点API的施用情状,并打听怎么活动是常规的,哪些是非平常的。
  • 限制API的使用,使恶意用户不可能停掉叁个API服务(DOS攻击),并且有本事阻止恶意的IP地址。
  • 将API密钥存款和储蓄在加密的安全密钥库中。

 

缓存和可伸缩性

  通过在系统层级解决通过远程调用来获得请求的数码,缓存升高了系统的可扩大性。服务通过在响应中安装headers来抓好缓存的力量。遗憾的是,HTTP
1.0中与缓存相关的headers与HTTP
1.1例外,由此服务器要同一时间协理三种版本。下表给出了GET请求要扶助缓存所不可不的最少headers群集,并交由了确切的叙述。

HTTP Header

描述

示例

Date

一呼百应重返的日子和时间(OdysseyFC1123格式)。

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

Cache-Control

一呼百应可被缓存的最大秒数(最大age值)。假诺响应不帮助缓存,值为no-cache。

Cache-Control: 360

Cache-Control: no-cache

Expires

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

财富自己最终被涂改的时间戳(OdysseyFC1123格式)。

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”

 

HTTP状态码(前10)

  以下是由RESTful服务或API再次回到的最常用的HTTP状态码,以及一些有关它们普及用法的粗略表明。其它HTTP状态码不太平日使用,它们仍然更优异,要么越来越尖端。大多数劳务套件只帮衬那个常用的状态码,以致只援救个中的一片段,并且它们都能健康办事。

  200 (OK) —— 日常的中标景色。表示成功的最遍布代码。

  201 (CREATED) ——(通过POST或PUT)创产生功。通过设置Location
header来含有多少个针对最新创造的能源的链接。

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

  304 (NOT MODIFIED)
—— 用于有规范的GET调用的响应,以减小带宽的行使。
要是运用这场合,那么必须为GET调用设置Date、Content-Location和ETag
headers。不包涵响应体。

  400 (BAD REQUEST)
—— 用于实施请求时大概引起无效状态的相似错误代码。如域名无效错误、数据丢失等。

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

  403 (FORBIDDEN)
—— 未授权的用户施行操作,没有权限访问能源,或许出于一些原因能源不可用(如时限等),使用该错误码。

  404 (NOT FOUND)
—— 无论财富存不设有,无论是不是有401、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.

网站

  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

相关文章

发表评论

电子邮件地址不会被公开。 必填项已用*标注

网站地图xml地图