教育惊叹世界|只看脸的约会是均等种何等的经验?

发布时间:2018-09-14  栏目:教育  评论:0 Comments

当即是平常世界里之故事:
顿时是稀松平常之同一天,阳光灿烂,整个蓝天晶莹剔透。人们行色匆匆。
立是干巴巴一龙中的8碰,在挤之地铁上,有的人埋头看手机,有的人自在电话,有的人眯着眼睡觉,有的人于大块头挤在一个聊角落。在另一个角落里,有一个男生,也发生一个女生,他们面临见了。他们最后各自看正在好之无绳电话机,没有开口,自然非会见生出新故事。

本文主要读者

众人会坐什么由遇到一起?
以会盖什么来头开始首先浅沾?

引言

丁潮里亿百年不遇底票房价值,我们相见了一道。无论是在公众号,还是微信,亦或某天的某部时刻,我们出了联。

REST是什么

我自己呢起了一些故事,比如在2010年碰上了百万点击率视频于官员抓去感化,比如上学搭讪被100大多独女生拒绝并做起搭讪社,比如疯狂学习写代码几单月也打出起了工作室赚钱,再以不出的间隔年、互联网产品经营课程等等。

  合接口

其实,我特别怪每一样码平常的工作,也鼎力为创造不同之感受,去考察与享受部分有味或干燥的业务。

    冲资源

即时是PM范儿这个群众号的老三年。过去底有数年,在此间埋头反思了成千上万做事息息相关的作业。在第三年,我接下会起搞事,搞事!

    透过特征来操作资源

PM范儿的新栏目:“好奇世界”。性感之总人口之趣集结,让咱共玩些有趣的试行。

    从今描述的音信

哼,开始首先软走。

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

  • 走内容

  无状态

咱俩还经历过形形色色的约会,聊过很多龙,也终究有静默尴尬的时刻。如果有平等上,相遇的一定量个旁观者,全程只用肢体语言来维系表达,会时有发生什么的化学反应?所以这次活动的名字吧“只看脸的约会”。由于当时是第一次等,脚下日月自己会亲自与!

  可缓存

  • 移步地点:北京

  • 哪些参与

  C-S架构

1.晚高回复同样摆而认为能够感动自己之相片及微信号;
2.符合条件的童鞋会添加微信,被关上一个故事屋(群);
3.于故事屋当中会发布得同与的任务。

  分层系统

-活动时间

  按需编码(可选)

1.清明晚底某同天,暂定4月8号。

REST快速提示

意在遇见你,搞事的眼前日月。

  采用HTTP动词表示有意义

公众号:PM范儿。

  合理的资源名

  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架构方式讲述了六种植设计则。这些用于架构的规划则,最早是由于Roy
Fielding在外的博士论文中提出并定义了RESTful风格。(详见http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)

  六个计划则分别是:

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

  以下是这些计划则的详实座谈:

统一接口

  统一接口准则定义了客户端和服务端之间的接口,简化和分手了框架结构,这样一来每个片都可独自演化。以下是接口统一之季只极:

  基于资源

  不同资源用为此URI来唯一标识。返回给客户端的特征和资源本身在概念上有所不同,例如服务端不见面直接传送一个数据库资源,然而,一些HTML、XML或JSON数据会展示部分数据库记录,如用芬兰语来表述要用UTF-8编码则要根据请求和服务器实现之底细来决定。

  通过特征来操作资源

  当客户端收到包含元数据的资源的风味时,在有权力的情况下,客户端都掌握的十足的消息,可以本着劳务端的资源进行删改。

  自描述的信

  每条消息还包含足够的数用于确认信息该怎么处理。例如要由网络媒体类型(已了解之要MIME类型)来认可要调用哪个解析器。响应同样为标志了她的缓存能力。

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

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

  除了上述内容他,HATEOS也代表,必要的时段链接也可是被含有在返回的body(或头部)中,以供URI来搜寻对象自我要涉对象。下文将针对斯进行重新详细的阐述。

  统一接口是每个REST服务统筹时之画龙点睛准则。

无状态

  正如REST是REpresentational State
Transfer的缩写,无状态异常要紧。本质上,这表明了拍卖要所需要的状态都包含在求我里,也发或是URI的同等部分、查询串参数、body或头部。URI能够唯一标识每个资源,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请求不能够改任何秘密的资源数量。测量和钉仍可能发,但才会更新数据如果不见面更新由URI标识的资源数量。

客观的资源名

  合理之资源名称或路径(如/posts/23而非是/api?type=posts&id=23)可以还显眼一个请求的目的。使用URL查询串来过滤数据是特别好之措施,但无该用于固定资源名称。

  适当的资源名称为服务端请求提供上下文,增加服务端API的可理解性。通过URI名称分层地查看资源,可以于使用者提供一个融洽之、容易了解的资源层次,以当她们之应用程序上应用。资源名称应当是名词,避免为动词。使用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次于以及调用10次于还是没被调用的功效同样。此外,GET(以及HEAD)是幂等的,这象征使用多独一样之呼吁与运用单个的呼吁最终还怀有相同的结果。

  不要通过GET暴露不安全之操作——它应永远都不可知改改服务器上的旁资源。

PUT

  PUT通常给用来创新资源。通过PUT请求一个曾经解的资源URI时,需要以求的body中含有对原资源的创新数据。

  不过,在资源ID是由客服端而休服务端提供的状况下,PUT同样可于用来创造资源。换句话说,如果PUT请求的URI中带有的资源ID值在服务器上未存,则用来创造资源。同时请的body中务必带有要创建的资源的数目。有人以为就会生歧义,所以只有真的需要,使用这种艺术来创造资源应该吃慎用。

  或者我们吧得以以body中提供由客户端定义的资源ID然后使用POST来创造新的资源——假设请求的URI中未分包要创的资源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(新资源的URI),等等。

  例如:

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

  当创建成功时,返回HTTP状态码201,并顺便一个职头信息,其中涵盖指向最先创建的资源的链接。

  POST请求既未是高枕无忧之而非是幂等的,因此它吃定义也非幂等性资源要。使用有限独一样的POST请求很可能会见导致创建两单包含相同信息之资源。

PUT和POST的始建于

  总之,我们建议以POST来创造资源。当由客户端来支配新资源有何等URI(通过资源名称或者ID)时,使用PUT:即只要客户端知道URI(或资源ID)是什么,则对拖欠URI使用PUT请求。否则,当由服务器或劳动端来决定创办的资源的URI时则运用POST请求。换句话说,当客户端在开创之前不知底(或无法清楚)结果的URI时,使用POST请求来创造新的资源。

DELETE

  DELETE很容易了解。它被用来冲URI标识删除资源。

  例如:

  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的办法以及资源URI,以及引进的返回值:

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创建资源URL时,这里有一部分聊技巧值得借鉴。

  从实质上谈,一个RESTFul
API最终还好为概括地当是千篇一律堆积URI的聚集,HTTP调用这些URI以及部分所以JSON和(或)XML表示的资源,它们吃生为数不少暗含了互相关联的链接。RESTful的不过寻址能力根本指URI。每个资源都出好的地方或URI——服务器会提供的各个一个卓有成效的音信还得以当作资源来明。统一接口的原则有地通过URI和HTTP动词的整合来解决,并符合利用正式及约定。

  以控制你系统被只要采用的资源时,使用名词来命名这些资源,而无是故动词或动作来定名。换句话说,一个RESTful
URI应该干到一个实际的资源,而不是关乎到一个动作。另外,名词还富有局部动词没有底属性,这为是另一个众所周知的素。

  一些资源的事例:

  • 系统的用户
  • 生登记的科目
  • 一个用户帖子的日子轴
  • 关爱其他用户的用户
  • 平篇有关骑马的篇章

  服务套件中之每个资源最少发生一个URI来标识。如果这个URI能表示肯定之义并且能充分描述她所表示的资源,那么其就是是一个最好之命名。URI应该有可预测性和子结构,这将推进提高它们的可理解性和可用性的:可预测指的是资源应该跟名保持一致;而分指的凡数码具有涉达成之构造。这并非REST规则或规范,但是其加重了针对性API的概念。

  RESTful
API是供被消费端的。URI的名称和组织应该以它所抒发的义传达给顾客。通常我们好不便掌握数码的鄂是啊,但是自君的数量及而该很有或夺品味找到要回给客户端的数目是啊。API是吗客户端而计划的,而非是吧您的多少。

  假设我们今天若讲述一个包客户、订单,列表项,产品等功用的订单系统。考虑一下我们欠怎么来叙述在斯服务中所波及到的资源的URIs:

资源URI示例

  为了在系面临插(创建)一个新的用户,我们得采取:

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

 

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

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

  使用PUT和DELETE来请求相同的URI,可以创新与去数据。

 

  下面是对活有关的URI的部分提议:

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

  用于创造新的活。

 

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

  分别用于读取、更新、删除编号也66432底制品。

 

  那么,如何也用户创建一个新的订单也?

  一栽方案是:

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

  这种方法得以就此来创造订单,但缺少相应的用户数据。

  

  为我们纪念啊用户创建一个订单(注意之间的关系),这个URI可能不敷直观,下面这URI则还鲜明一些:

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

  现在咱们领略她是吗编号33245底用户创建一个订单。

 

  那下面这个请返回的凡啊为?

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

  可能是一个号为33245之用户所创建或者享有的订单列表。注意:我们好屏蔽对拖欠URI进行DELETE或PUT请求,因为其的操作对象是一个汇聚。

 

  继续深入,那下面这URI的乞求又象征什么吧?

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

  可能是(为编号33245底用户)增加一个码吧8769的订单条目。没错!如果运用GET方式呼吁是URI,则会回到这个订单的拥有条条框框。但是,如果这些条款与用户信息无关,我们将见面提供POST
www.example.com/orders/8769/lineitems
这个URI。

  从返回的这些章来拘禁,指定的资源或会见产生多独URIs,所以我们或许吗亟需而供这样一个URI
GET
http://www.example.com/orders/8769
,用来在匪掌握用户ID的事态下基于订单ID来询问订单。

 

  更进一步:

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

  可能只是回跟个订单中之第一独章。

  现在你应该掌握啊是分开层结构了。它们并无是严峻的平整,只是为着保险在你的劳动着这些强制的组织能再次爱受用户所知晓。与具有软件开发中的技巧一样,命名是成之根本。

  

  多看有些API的演示并学会控制这些技能,和您的队友一起来圆而API资源的URIs。这里发生部分APIs的事例:

  • Twitter: https://dev.twitter.com/docs/api
  • Facebook: http://developers.facebook.com/docs/reference/api/
  • LinkedIn: https://developer.linkedin.com/apis

资源命名的反例

  前面我们既讨论过局部相当的资源命名的例证,然而有时有反面的事例吗甚有教育意义。下面是有些非太具RESTful风格的资源URIs,看起比混乱。这些都是大错特错的例子! 

  首先,一些serivices往往使单一的URI来指定服务接口,然后经查询参数来指定HTTP请求的动作。例如,要更新编号12345之用户信息,带有JSON
body的呼吁或是这般:

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

  尽管地方URL中之”services”的斯节点是一个名词,但这个URL不是自说的,因为对拥有的恳求而言,该URI的层级结构都是同一的。此外,它用GET作为HTTP动词来实施一个更新操作,这简直就是反人类(甚至是千钧一发的)。

  下面是另外一个更新用户之操作的例子:

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

  以及它们的一个变种:

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

  你见面时看看于任何开发者的服务套件中生好多如此的用法。可以看到,这些开发者试图去创造RESTful的资源名称,而且就出了片向上。但是若还是会辨识出URL中的动词短语。注意,在这URL中我们无需”update”这个词,因为我们得因HTTP动词来好操作。下面这URL正好说明了当时一点:

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

  这个请又有PUT和”update”,这会指向消费者出迷惑!这里的”update”指的是一个资源为?因此,这里我们费些口舌也是想而可知明白……

复数

  让咱来讨论一下复数和“单数”的争辩…还没听说过?但这种争议确实是,事实上它们可以归纳为者题目……

  在你的层级结构中URI节点是否要被命名也单数或复数形式呢?举个例,你用来寻找用户资源的URI的命名是否用像下这样:

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

  或者:

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

  两栽艺术都尚未问题,但通常咱们都见面选下复数命名,以使你的API
URI在装有的HTTP方法吃保持一致。原因是根据这样平等种考虑:customers是服务套件中的一个凑,而ID33245的斯用户则是者集中的内一个。

  按照这个规则,一个行使复数形式之多节点的URI会是这么(注意粗体部分):

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

  “customers”、“orders”以及“lineitems”这些URI节点都施用的凡复数形式。

  这代表你的每个根资源只需要简单只基本的URL就足以了,一个用来创造集合内之资源,另一个据此来冲标识符获取、更新和去资源。例如,以customers为例,创建资源可以利用下的URL进行操作:

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

  而读取、更新和去资源,使用下的URL操作:

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

  正使前方提到的,给一定的资源或来差不多只URI,但当一个最为小的整的增删改查功能,利用有限个大概的URI来拍卖就足够了。

  或许你晤面咨询:是否以微情况下复数没有意义?嗯,事实上是这般的。当没有汇概念的下(此时复数没有意义)。换句话说,当资源就发一个之情事下,使用单数资源名称也是足以的——即一个单纯的资源。例如,如果来一个单一的完全布局资源,你可利用一个单数名称来代表:

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

  注意这里少configuration的ID以及HTTP动词POST的用法。假设每个用户有一个部署来说,那么这URL会是这般:

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

  通过这种方式,在URI中指定返回表征的格式,可以增强URL的可见性。例如,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头,服务端要以支持封装和免封装的响应,你不能不实现从定义之路——因为这些格式不是正经的型。这大大增加了客户端和劳动端的错综复杂。请参见RFC
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是什么”同一省吃也波及了。

  根据Roy
Fielding在外的博客中之叙说(http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertextdriven),REST接口中极着重之局部是超文本的使用。此外,他还指出,在叫闹任何有关的音信之前,一个API应该是可用和而领略的。也就是说,一个API应当可以由此其链接导航及多少的逐条组成部分。不建议就回去纯数据。

  不过当下的业界先驱们连无经常下这种做法,这反映了HATEOAS仅仅以成熟度模型中的使用率还胜。纵观众多之服务体系,它们多返回重新多的数目,而回到的链接却大少(或者没)。这是负Fielding的REST约定的。Fielding说:“信息的各个一个只是寻址单元都带一个地址……查询结果该呈现吧一个带有摘要信息之链接清单,而未是目标往往组。”

  另一方面,简单粗暴地用合链接集合返回会大大影响网络带来富。在实质上情况屡遭,根据所待的标准或采用状态,API接口的通信量要依据服务器响应中超文本链接所富含的“摘要”数量来抵消。

  同时,充分利用HATEOAS可能会见大增实现之复杂,并针对劳动客户端有显著的承负,这一定给降低了客户端以及劳务器端开发人员的生产力。因此,当务之急是一旦平衡超链接服务实施和现有可用资源之间的题材。

  超链接最好小化的做法是当最好酷限度地减小客户端和服务器之间的耦合的同时,提高劳动端的可用性、可操纵性和可理解性。这些极小化建议是:通过POST创建资源并由GET请求返回集合,对于有分页的事态后我们见面提到。

太小化链接推荐

  于create的用例中,新建资源的URI(链接)应该于Location响应头中回到,且应中心是空的——或者仅仅含有新建资源的ID。

  对于自服务端返回的特性集合,每个表征应该在她的链接集合中带走一个极小的“自身”链接属性。为了有利于分页操作,其它的链接可以放在一个独立的链接集合中回到,必要经常好蕴涵“第一页”、“上同一页”、“下一致页”、“最后一页”等消息。

  参照下文链接格式局部的例证获取更多信息。

链接格式

  参照整个链接格式的正规,建议遵守一些看似Atom、AtomPub或Xlink的品格。JSON-LD也是,但并没被普遍使用(如果已为用了)。目前标准最普遍的法是用含有”rel”元素和含有资源总体URI的”href”元素的Atom链接格式,不包含其他身份验证或询问字符串参数。”rel”元素得以蕴涵标准值”alternate”、”related”、”self”、”enclosure”和”via”,还有分页链接的“第一页”、“上同页”、“下同样页”,“最后一页”。在用时方可于定义并累加应用它们。

  一些XML
Atom格式的概念对用JSON格式表示的链接来说是无济于事的。例如,METHOD属性对于一个RESTful资源来说是免欲的,因为于一个加以的资源,在有支持之HTTP方法(CRUD行为)中,资源的URI都是平之——所以单独列有这些是从来不必要之。

  让我们选一些现实的例子来更为证实及时一点。下面是调用创建新资源的呼吁后底应:

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

  下面是作应头集合中蕴藏创建新资源的URI的Location部分:

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

  返回的body可以啊空,或者隐含一个为装进的应(见下文封装响应)。

  下面的例证通过GET请求获取一个勿带有分页的特色集合的JSON响应:

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

  注意,links数组中之每一样宗都包含一个针对“自身(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。另外一个提案是由于Douglas
Crockford提出的,可以翻此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和跨域资源共享(CORS)。JSONP或“填充的JSON”是同等种植使模式,它提供了一个法要来自不同域中之服务器的数。其工作方法是打服务器返回任意的JavaScript代码,而休是JSON。客户端的应由JavaScript解析器进行分析,而不是直接解析JSON数据。另外,CORS是均等种web浏览器的技巧标准,它为web服务器定义了扳平栽方法,从而允许服务器的资源得以为无同域的网页访问。CORS被当是JSONP的新型替代品,并且可于抱有现代浏览器支持。因此,不建议采取JSONP。任何情形下,推荐选择CORS。

支持CORS

  在服务端实现CORS很简短,只待以殡葬响应时顺便HTTP头,例如: 

Access-Control-Allow-Origin: *

  只有在数额是公物使用的气象下才会将访问来源设置为”*”。大多数情形下,Access-Control-Allow-Origin头应该指定哪些域可发起一个CORS请求。只有用跨域访问的URL才装CORS头。

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

  以上Access-Control-Allow-Origin头中,被设置为单允许被信赖的地面可以看。

Access-Control-Allow-Credentials: true

  只于需要经常才使方面这header,因为一旦用户已报到的话,它会以发送cookies/sessions。

  这些headers可以经过web服务器、代理来进展配置,或者由服务器本身发送。不引进以服务端实现,因为老无灵活。或者,可以动用方面的老二种方式,在web服务器上布置一个所以空格分隔的地域的列表。更多关于CORS的情好参照这里:http://enable-cors.org/。

支持JSONP

  JSONP通过下GET请求避开浏览器的限,从而实现对具备服务的调用。其行事原理是请求方在请的URL上补偿加一个字符串查询参数(例如:jsonp=”jsonp_callback”),其中“jsonp”参数的值是JavaScript函数称呼,该函数在发应返回时用会见给调用。

  由于GET请求中莫含呼吁求体,JSONP在利用时有着严重的局限性,因此数据要透过字符串查询参数来传递。同样的,为了支持PUT,POST和DELETE方法,HTTP方法要也经过字符串查询参数来传递,类似_method=POST这种样式。像这样的HTTP方法传送方式是未引进应用的,这会让服务处于安全风险之中。

  JSONP通常在一部分免支持CORS的老旧浏览器中以,如果一旦反成为支持CORS的,会潜移默化整个服务器的架构。或者我们呢可以通过代办来兑现JSONP。总之,JSONP正在让CORS所取代,我们应尽量地运CORS。

  为了当服务端支持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通常只能展现大数额集中的一致有点片数据。在数据集的增长速度不确定的情下,限制默认返回的数据量是老大有必要之。以Twitter为例,要收获有用户的推文(通过个人主页的时轴),如果没有特别指定,请求默认只见面回到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单记录,假要数据集中至少有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

  于大部场面下,这种分页方式还没问题。但有时会出这种状况,就是一旦赶回的记录数据无法直接代表成数据集中的行号。还有即使是起来数据集的浮动快,不断会发出新的数据插入到多少汇总,这样自然会招分页出现问题,一些复的数或许会见冒出在不同的页中。

  按日期排列的数据集(例如Twitter
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”之如。用字符串查询参数实现的伸手URI如下:

  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进行版本化管理是避这种根本变化的平种植中办法。

经内容商支持版本管理

  以往,版本管理通过URI本身的本号来成功,客户端在伸手的URI中标明要获得的资源的版本号。事实上,许多坏公司如果Twitter、Yammer、Facebook、Google等不时以他们的URI里使用版本号。甚至像WSO2这样的API管理工具也会于她的URLs中要求版本号。

  面向REST原则,版本管理技术飞速发展。因为她不分包HTTP规范中置的header,也无支持不过当一个初的资源或概念被引入时才应添加新URI的眼光——即版本不是表现形式的变通。另一个反对的理是资源URI是未会见随时间改变的,资源就是资源。

  URI应该能大概地识别资源——而无是它们的“形状”(状态)。另一个尽管是必指定响应的格式(表征)。还有一些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被用来代表所欲之应格式(以及示例中的版本号),注意上述两只同之URI是安形成在不同的本被分辨资源的。或者,如果客户端需要一个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来增长响应

  可选。见RDF(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或GMT时间来存储、处理与缓存时间戳。这将使得化解日期与时空之题目。

Body内容中的日子/时间序列化

  有一个大概的计好缓解这些问题——在字符串中总用同样之格式,包括时间片(带有时区信息)。ISO8601时间格式是一个不利的缓解方案,它用了净增强的时间格式,包括小时、分钟、秒和秒的小数部分(例如yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)。建议在REST服务之body内容被(请求和响应均包括)使用ISO8601代表享有的日期格式。

  顺便取一下,对于那些基于JAVA的劳动以来,DateAdapterJ库使用DateAdapter,Iso8601TimepointAdapter和HttpHeaderTimestampAdapter类可以非常容易地剖析和格式化ISO8601日期以及岁月,以及HTTP
1.1
header(RFC1123)格式。可以自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使用外一样种不同的格式。在被RFC1123还给之RFC822中指出,该格式包括了各种日期、时间与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。

身份验证

  时最好好的做法是使用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

响应返回的日子和时空(RFC1123格式)。

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

资源本身最后被改动的时光穿(RFC1123格式)。

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

留下评论