亿万先生手机版:基于能源

本文首要读者

引言

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架构方式汇报了四种设计法规。那些用于架构的设计法则,最早是由RoyFielding在她的大学生随想中提议并定义了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内容、查询串参数、央浼头和U帕杰罗I(财富名称)来传送状态。服务端通过body内容,响应码和响应头传送状态给客户端。那项技术被称为超媒体(或超文本链接)。

  除了上述故事情节外,HATEOS也意味,须要的时候链接也可被含有在回去的body(或尾部)中,以提供UEvoqueI来搜寻对象自己或提到对象。下文将对此开始展览更详尽的论述。

  统一接口是各样REST服务统一计划时的不可或缺准绳。

无状态

  正如REST是REpresentational State
Transfer的缩写,无状态很关键。本质上,那标识了拍卖央求所需的情景已经包蕴在伸手笔者里,也许有比异常的大可能率是USportageI的一有的、查询串参数、body或底部。U兰德TiggoI能够唯一标记每种财富,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诉求不能够退换任何秘密的财富数量。衡量和追踪仍可能发生,但只会更新数据而不会更新由UEnclaveI标志的能源数量。

客观的能源名

  合理的能源名称只怕路线(如/posts/23实际不是/api?type=posts&id=23)能够更简惠氏个诉求的指标。使用U哈弗L查询串来过滤数据是很好的章程,但不该用于固定能源名称。

  适当的能源名叫服务端恳求提供上下文,扩大服务端API的可明白性。通过ULX570I名称分层地翻看能源,能够给使用者提供一个谐和的、轻巧领悟的财富档次,以在他们的应用程序上利用。能源名称应当是名词,防止为动词。使用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”链接至少是十二分管用的。

 

定义

幂等性

  不要从字面意思来领悟什么是幂等性,恰恰相反,那与一些意义纷乱的园地非亲非故。下边是来自维基百科的解说:

在Computer科学中,术语幂等用于更全面地描述一个操作,贰回或频仍施行该操作发生的结果是一致的。依照使用的上下文,这也可能有分歧的意思。举例,在章程可能子例程调用具有副成效的境况下,意味着在首先调用之后被改造的情景也保证不改变。

  从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次和调用11回依然尚未被调用的功效一样。其余,GET(以及HEAD)是幂等的,那意味着使用八个同样的恳求与使用单个的乞请最后都有着一致的结果。

  不要通过GET暴光不安全的操作——它应该永世都不能够改改服务器上的另外能源。

PUT

  PUT平时被用来更新能源。通过PUT诉求贰个已知的财富U奥迪Q5I时,供给在呼吁的body中含有对原本能源的换代数据。

  不过,在财富ID是由客服端而非服务端提供的情形下,PUT一样能够被用来成立能源。换句话说,假如PUT诉求的UWranglerI中满含的财富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不是八个有惊无险的操作,因为它会修改(或成立)服务器上的情事,但它是幂等的。换句话说,假若您使用PUT成立只怕更新能源,然后再一次调用,能源照旧存在並且状态不会爆发变化。

  举例,若是在财富增量计数器中调用PUT,那么那些调用方法就不再是幂等的。这种景观不常候会发出,且恐怕能够注脚它是非幂等性的。但是,提出维持PUT央求的幂等性。并猛烈提出非幂等性的乞求使用POST。

POST

  POST央浼常常被用来创建新的财富,非常是被用来创设从属能源。从属财富即归属于别的能源(如父能源)的能源。换句话说,当创造贰个新能源时,POST央浼发送给父能源,服务端负担将新财富与父财富拓展关联,并分配七个ID(新能源的ULX570I),等等。

  例如:

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

  当创制作而成功时,再次来到HTTP状态码201,并顺便一个地方头消息,个中含有指向开始创立的能源的链接。

  POST哀告既不是安枕而卧的又不是幂等的,因而它被定义为非幂等质量源伏乞。使用七个一律的POST乞请很可能会促成创造多个满含同样新闻的财富。

PUT和POST的创始比较

  不问可见,大家建议采纳POST来创建能源。当由客户端来调节新财富具备怎么着ULacrosseI(通过财富名称或ID)时,使用PUT:即假如客户端知道U安德拉I(或财富ID)是如何,则对该U凯雷德I使用PUT央求。不然,当由服务器或服务端来调控创办的财富的U卡宴I时则利用POST须求。换句话说,当客户端在创设此前不精通(或不能够清楚)结果的U昂科拉I时,使用POST央求来创建新的财富。

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操作。

  不过,这里有一个有关DELETE幂等性的警示。在贰个能源上第一回调用DELETE往往会回来404(未找到),因为该能源已经被移除了,所以找不到了。那使得DELETE操作不再是幂等的。假设财富是从数据库中除去并非被总结地方统一规范记为除去,这种景观供给适合的量妥协。

  下表总括出了第一HTTP的办法和能源U奔驰G级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奥迪Q5L时,这里有一对小手艺值得借鉴。

  从精神上讲,一个RESTFul
API最后都足以被略去地作为是一群U大切诺基I的集结,HTTP调用这个ULacrosseI以及部分用JSON和(或)XML表示的能源,它们中有那个包蕴了交互关系的链接。RESTful的可寻址手艺主要借助U福睿斯I。每一个财富都有本身的地方或UPAJEROI——服务器能提供的每贰个卓有成效的新闻都足以看做财富来公开。统一接口的口径部分地经过UENCOREI和HTTP动词的咬合来缓慢解决,并符合利用正式和预定。

  在支配你系统中要动用的能源时,使用名词来定名那些财富,并非用动词或动作来命名。换句话说,三个RESTful
U福睿斯I应该提到到多个切实的财富,实际不是关系到多少个动作。其余,名词还怀有部分动词未有的习性,那也是另一个显著的因素。

  一些能源的事例:

  • 系统的用户
  • 学员注册的课程
  • 三个用户帖子的光阴轴
  • 关爱别的用户的用户
  • 一篇关于骑马的小说

  服务套件中的每一种财富最少有多个U传祺I来标记。假诺这一个UTiguanI能表示必定的意义何况能够尽量描述它所表示的能源,那么它正是二个最佳的命名。U奥迪Q3I应该有所可预测性和支行结构,那将力促巩固它们的可通晓性和可用性的:可预测指的是能源应该和名称保持一致;而分层指的是多少颇具关系上的结构。那而不是REST法则或正规,不过它加重了对API的定义。

  RESTful
API是提须要费用端的。U奥德赛I的名号和布局应该将它所发挥的意义传达给买主。平时大家很难通晓数据的边际是怎么样,不过从你的数目上您应当很有望去品尝找到要回到给客户端的数额是怎么样。API是为客户端而规划的,实际不是为您的多寡。

  即使大家明天要呈报叁个包罗客户、订单,列表项,产品等职能的订单系统。考虑一下大家该怎么来描述在这些服务中所涉及到的能源的UKugaIs:

资源URI示例

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

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

 

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

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

  使用PUT和DELETE来伏乞一样的U揽胜I,能够立异和删除数据。

 

  下边是对产品有关的UCRUISERI的局地提议:

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

  用于创造新的制品。

 

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

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

 

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

  一种方案是:

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

  这种形式得以用来创设订单,但缺少相应的用户数量。

  

  因为我们想为用户创设三个订单(注意之间的关联),这几个U汉兰达I或然相当不足直观,上边那些UCR-VI则更清楚一些:

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

  未来大家知道它是为编号33245的用户创造二个订单。

 

  那上面那个乞请重返的是如何啊?

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

  可能是三个数码为33245的用户所创造或富有的订单列表。注意:大家得以屏蔽对该U冠道I实行DELETE或PUT诉求,因为它的操作对象是多少个集合。

 

  继续深入,那下边那几个UEscortI的伸手又表示怎么着吗?

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

  或者是(为编号33245的用户)扩展一个编号为8769的订单条款。没有错!假设选用GET格局呼吁那些U逍客I,则会回到那么些订单的兼具条条框框。可是,就算这个条目款项与用户音讯非亲非故,我们将会提供POST
www.example.com/orders/8769/lineitems
这个URI。

  从再次来到的这个条目来看,钦定的能源恐怕会有八个U大切诺基Is,所以我们大概也急须要提供这么三个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奥迪Q5Is。这里有一部分APIs的事例:

能源命名的反例

  前面我们曾经切磋过一些卓殊的财富命名的事例,然则不经常一些反面包车型地铁例子也很有教育意义。上面是一些不太具有RESTful风格的能源UCRUISERIs,看起来相比散乱。这几个都是谬误的例证! 

  首先,一些serivices往往利用单一的U本田CR-VI来钦定服务接口,然后通过询问参数来钦命HTTP央求的动作。比方,要创新编号12345的用户音讯,带有JSON
body的呼吁或然是如此:

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

  尽管地点U昂科拉L中的”services”的那么些节点是一个名词,但这一个U大切诺基L不是自解释的,因为对此有着的哀告来讲,该URAV4I的层级结构都以同样的。其余,它选拔GET作为HTTP动词来试行三个创新操作,这简直正是反人类(乃至是剑拔弩张的)。

  上边是别的贰个立异用户的操作的事例:

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

  以及它的二个变种:

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

  你会时常来看在别的开荒者的劳务套件中有一不计其数那样的用法。能够见见,这么些开垦者试图去成立RESTful的能源名称,并且早就有了某个发展。但是你还是可以辨识出ULX570L中的动词短语。注意,在那些U奥迪Q5L中大家不要求”update”这些词,因为大家能够凭仗HTTP动词来产生操作。上边这几个UHighlanderL正好表达了那或多或少:

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

  这么些央浼同一时候设有PUT和”update”,那会对顾客发生吸引!这里的”update”指的是叁个能源吗?因而,这里我们费些口舌也是旨在你能够领略……

复数

  让我们来研讨一下复数和“单数”的争论…还没传说过?但这种纠纷确实存在,事实上它能够总结为这些难题……

  在你的层级结构中UTucsonI节点是或不是需求被取名称为单数或复数方式吗?举个例证,你用来查找用户能源的UEnclaveI的命名是不是必要像上边那样:

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

  或者:

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

  三种办法都没难题,但平日我们都会选择选用复数命名,以使得你的API
UENCOREI在享有的HTTP方法中保持一致。原因是依赖那样一种思量:customers是劳动套件中的一个成团,而ID33245的那个用户则是以此会集中的在那之中一个。

  根据这么些法规,二个采纳复数情势的多节点的U安德拉I会是如此(注意粗体部分):

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

  “customers”、“orders”以及“lineitems”那几个UOdysseyI节点都采纳的是复数情势。

  那意味你的各样根能源只须要两在那之中央的U瑞鹰L就足以了,一个用来创制集结内的财富,另三个用来依照标志符获取、更新和删除能源。比如,以customers为例,创建能源得以选取上面包车型客车U冠道L举行操作:

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

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

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

  正如前方提到的,给定的能源恐怕有多个U安德拉I,但作为三个微小的完好的增加和删除改查功效,利用多少个简易的UPRADOI来拍卖就够了。

  大概你会问:是还是不是在多少意况下复数未有意义?嗯,事实上是这么的。当未有集合概念的时候(此时复数没风趣)。换句话说,当财富唯有一个的景观下,使用单数财富名称也是足以的——即三个单一的能源。譬喻,假诺有二个纯粹的完好安排能源,你能够应用一个单数名称来代表:

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

  注意这里紧缺configuration的ID以及HTTP动词POST的用法。倘使各个用户有多少个安插来讲,那么这一个UHavalL会是那样:

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

  通过这种方法,在UCR-VI中钦定再次回到表征的格式,能够进步UEnclaveL的可知性。比如,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头,服务端要同有的时候候协理封装和未封装的响应,你不可能不兑现自定义的花色——因为那几个格式不是行业内部的档案的次序。那大大扩展了客户端和服务端的繁杂。请参见XC60FC
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约定的。Fielding说:“消息的每一个可寻址单元都带领贰个地方……查询结果应该展现为贰个涵盖摘要消息的链接清单,实际不是目的数组。”

  另一方面,轻易阴毒地将全体链接集合重回会大大影响互联网带宽。在实情中,依照所需的标准或采纳景况,API接口的通信量要依附服务器响应中超文本链接所富含的“摘要”数量来抵消。

  同有的时候间,丰裕利用HATEOAS只怕会大增完成的目迷五色,并对服务客户端发生刚强的承负,这一定于裁减了客户端和劳动器端开采职员的生产力。由此,当劳之急是要平衡超链接服务实施和水保可用财富之间的主题素材。

  超链接最小化的做法是在最大限度地缩减客户端和服务器之间的耦合的同偶尔候,升高服务端的可用性、可垄断(monopoly)性和可掌握性。那些最小化建议是:通过POST制造财富并从GET乞请重回集结,对于有分页的动静前边大家会波及。

小小化链接推荐

  在create的用例中,新建能源的URubiconI(链接)应该在Location响应头中回到,且响应宗旨是空的——或许只含有新建能源的ID。

  对于从服务端再次回到的性状集结,每一个表征应该在它的链接会集中带领一个微细的“本身”链接属性。为了有助于分页操作,别的的链接能够献身二个独门的链接群集中回到,须求时能够包涵“第一页”、“上一页”、“下一页”、“最终一页”等消息。

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

链接格式

  参照整个链接格式的正统,提议听从一些近似Atom、AtomPub或Xlink的风骨。JSON-LD也未可厚非,但并从未被普及选拔(假使已经被用过)。最近正规最遍布的不二诀要是行使含有”rel”成分和含有能源全部USportageI的”href”成分的Atom链接格式,不富含其余身份验证或询问字符串参数。”rel”成分得以分包规范值”alternate”、”related”、”self”、”enclosure”和”via”,还应该有分页链接的“第一页”、“上一页”、“下一页”,“最终一页”。在急需时能够自定义并加上应用它们。

  一些XML
Atom格式的定义对于用JSON格式表示的链接来说是无效的。譬喻,METHOD属性对于四个RESTful能源来讲是无需的,因为对此四个加以的能源,在有着帮忙的HTTP方法(CRUD行为)中,能源的U昂科雷I都以均等的——所以单独列出这么些是不须要的。

  让我们举一些切实的例证来一发验证那或多或少。下边是调用创设新财富的央求后的响应:

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

  下边是响应头会集中包涵创立新财富的UQX56I的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。别的二个提案是由DougRussCrockford提议的,能够查阅这里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本田UR-VS)。JSONP或“填充的JSON”是一种选择方式,它提供了多少个主意央求来自区别域中的服务器的数据。其行事方法是从服务器重返放肆的JavaScript代码,实际不是JSON。客户端的响应由JavaScript分析器举办深入分析,并不是一贯深入分析JSON数据。别的,COEscortS是一种web浏览器的技巧标准,它为web服务器定义了一种办法,进而允许服务器的能源得以被不一致域的网页访谈。CO酷威S被用作是JSONP的新式替代品,而且能够被全数当代浏览器补助。因而,不提出使用JSONP。任何景况下,推荐选用CO本田CR-VS。

支持CORS

  在服务端实现CO福特ExplorerS很简单,只须求在出殡和埋葬响应时顺便HTTP头,举例: 

Access-Control-Allow-Origin: *

  独有在数据是公共使用的情状下才会将访问来源设置为”*”。大大多气象下,Access-Control-Allow-Origin头应该钦命哪些域可以发起三个COEscortS央浼。唯有需求跨域访谈的URubiconL才设置CO奥迪Q5S头。

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

支持JSONP

  JSONP通过使用GET诉求避开浏览器的限制,从而实现对具备服务的调用。其行事规律是央求方在乞请的UCRUISERL上加多七个字符串查询参数(举例:jsonp=”jsonp_callback”),在那之中“jsonp”参数的值是JavaScript函数名,该函数在有响应重临时将会被调用。

  由于GET须求中向来不包涵央浼体,JSONP在行使时有着严重的局限性,由此数据必须通过字符串查询参数来传递。同样的,为了援救PUT,POST和DELETE方法,HTTP方法必须也经过字符串查询参数来传递,类似_method=POST这种情势。像这么的HTTP方法传送格局是不推荐使用的,那会让服务处于安全危害之中。

  JSONP平常在有的不帮衬CO大切诺基S的老旧浏览器中央银行使,借使要改成协助CO汉兰达S的,会影响整个服务器的框架结构。或然大家也足以因此代理来兑现JSONP。可想而知,JSONP正在被COEnclaveS所替代,大家理应尽量地应用CORubiconS。

  为了在服务端匡助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条记下。

  除了限制重回的数据量,大家还亟需思考如何对天意据集实行“分页”或下拉滚动操作。成立数量的“页码”,再次回到大数目列表的已知片段,然后标出数据的“前一页”和“后一页”——这一展现被称之为分页。别的,大家恐怕也亟需钦命响应上将包涵怎么着字段或质量,进而限制再次回到值的多寡,而且我们希望最后能够通过特定值来拓展询问操作,并对重返值进行排序。

  有三种入眼的主意来还要限制查询结果和施行分页操作。首先,我们得以创建多个目录方案,它可以以页码为导向(央浼中要交给每一页的记录数及页码),或许以记录为导向(恳求中央市直机关接提交第一条记下和最后一条记下)来规定重回值的起第壹地方。譬如,这两种方式分别代表:“给出第五页(假若每页有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

  在大部情况下,这种分页形式都未曾难点。但有的时候会有这种情景,正是要回去的笔录数据不能直接代表成多少集中的行号。还应该有就是有个别数据集的变迁一点也不慢,不断会有新的数额插入到数量聚焦,这样必然会导致分页出现难题,一些再次的多寡大概会油然则生在不相同的页中。

  按日期排列的数据集(举个例子Twitterfeed)正是一种普及的景色。即便你如故得以对数据开始展览分页,但有的时候用”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)。

  通过引进一组布满的、公认的分隔符,用于过滤的表明式能够以老大直观的款式被运用。用那几个分隔符来设置过滤查询参数的值,这么些分隔符所成立的参数名/值对能够特别轻巧地棉被和衣服务端分析并加强数据查询的习性。近期已有的分隔符满含用来分隔各类过滤短语的竖线(”|”)和用来分隔参数名和值的双冒号(”::”)。那套分隔符丰盛独一,并符合大多数场馆,同时用它来营造的字符串查询参数也越加轻巧领会。下边将用三个大约的例子来介绍它的用法。假使大家想要给名称为“托德”的用户们发送哀告,他们住在圣Juan,有着“Grand
Poobah”之称。用字符串查询参数落成的必要U奥德赛I如下:

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

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

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

  轻松而使得。有关大小写敏感的标题,要依靠具体情形来看,但看来,在毫无关怀大小写的图景下,过滤效果能够很好地运维。若查询参数名/值对中的属性值未知,你也得以用星号(”*”)来代替。

  除了简单的声明式和通配符之外,若要进行更目迷五色的询问,你不可能不要引进运算符。在这种情形下,运算符自个儿也是属性值的一有个别,能够被服务端分析,而不是产生属性名的一有的。当需求复杂的query-language-style(查询语言风格)功用时,可参照Open
Data Protocol (OData) Filter System Query
Option表明中的查询概念(详见http://www.odata.org/documentation/uriconventions#FilterSystemQueryOption)。

排序

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

  同样,大家这里只思量部分相比轻松的景观。推荐应用排序字符串查询参数,它满含了一组用分隔符分隔的属性名。具体做法是,默许对种种属性名按升序排列,假设属性名有前缀”-“,则按降序排列。用竖线(”|”)分隔各样属性名,那和前面过滤效果中的参数名/值对的做法同样。

  比如,假使大家想按用户的姓和名展开升序排序,而对雇佣时间展开降序排序,央浼将是这么的:

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

  再一次重申一下,查询参数名/值对中的属性名要和服务端再次回到的品质名相相称。另外,由于排序操作比较复杂,大家只对需求的能源提供排序效能。假若须求的话也得以在客户端对小的能源会集进行排列。

 

服务版本管理

   直爽地讲,一提及版本就能够令人感觉很不方便,很辛劳,不太轻松,以致会令人以为哀痛——因为那会追加API的复杂度,并还要可能会对客户端暴发部分震慑。因而,在API的规划中要尽量制止多个不等的本子。

  不补助版本,不将版本调节作为不佳的API设计的重视。要是你在APIs的设计中引进版本,那迟早都会让您抓狂。由于重返的多寡通过JSON来表现,客户端会由于分裂的本子而接受到差异的性质。那样就能够存在有的难题,如从内容我和验证法规方面退换了一个已存在的天性的意思。

  当然,大家爱莫能助防止API或者在一些时候须要转移返回数据的格式和内容,而那也将造成花费端的一些扭转,大家应当防止实香港行政局地至关心注重要的调动。将API进行版本化管理是制止这种根本调换的一种有效措施。

经过剧情协商帮忙版本管理

  未来,版本处理通过URAV4I本人的本子号来实现,客户端在乞请的U瑞虎I中表明要收获的财富的版本号。事实上,大多大市廛如推特(TWTR.US)、Yammer、Facebook、谷歌(Google)等临时在她们的UHavalI里使用版本号。乃至像WSO2那样的API管理工科具也会在它的U大切诺基Ls中须要版本号。

  面向REST原则,版本管理工夫快捷发展。因为它不含有HTTP标准中放置的header,也不协助仅当四个新的能源或概念被引进时才应该增多新U昂科拉I的见地——即版本不是表现情势的变通。另三个反对的理由是能源UQX56I是不会随时间退换的,能源正是财富。

  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被用来表示所企望的响应格式(以及示例中的版本号),注意上述八个同样的UPRADOI是何许变成在差异的本子中分辨财富的。大概,倘诺客户端须要三个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来进步响应

  可选。见HavalDF(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和HttpHeaderTimestampAdapter类可以极度轻巧地深入分析和格式化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使用另一种不相同的格式。在被中华VFC1123更替的ENVISIONFC82第22中学指出,该格式包罗了种种日期、时间和date-time格式。可是,提出始终使用时间戳格式,在你的request
headers中它看起来像这么:

  Sun, 06 Nov 1994 08:49:37 GMT

  可是,这种格式未有虚拟飞秒大概秒的十进制小数。Java的SimpleDataFormat的格式串是:”EEE,
dd MMM yyyy HH:mm:ss ‘GMT'”。

 

护卫服务的平安

  Authentication(身份ID明)指的是确认给定的伏乞是从服务已知的某个人(或有些系统)发出的,且诉求者是他本人所注解的要命人。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

响应重返的日子和岁月(兰德酷路泽FC1123格式)。

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

财富本人最终被修改的日子戳(RubiconFC1123格式)。

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地图