可缓存

《万物简史》

随即是一样统关于现代是发展史的既通俗易懂又感人的书写,作者用清晰明了、幽默风趣的笔法,将宇宙大爆炸到人类文明发展历程面临所生的应有尽有妙趣横生的故事一一收入笔下。

科学 1

至于现代对发展史的既是通俗易懂又感人的书写

统一接口

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

《趣味生活简史》

夫作灵感源自于作者一糟石破天惊的觉察:房屋不是避开历史的避难所,而是历史之末段归宿。在作者看来,无论世界上产生了啊,不管人们发现了哟,创造了哟,或冲争夺了呀,最终都见面坐这种还是那种办法投射到公的妻妾。战争、饥荒、工业革命、启蒙运动……这些近似与我们去遥远的历史恐怕便隐藏在公的沙发里与五斗橱里、在您窗帘的褶子里、在公松软的枕里、在你下墙上的油漆里、在您小之自来水管道甚至抽水马桶里。于是,作者决定探究每间房在住家生活之演变过程中所从的来意。

科学 2

著灵感源自于作者一潮石破天惊的觉察

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

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

  除了上述情节外,HATEOS也象征,必要的下链接也不过吃含有在回来的body(或头部)中,以提供URI来寻找对象自我或干对象。下文将对斯开展重复详尽的阐发。

  统一接口是每个REST服务计划时之必需准则。

《荒原狼》

(Der Steppenwolf(也翻作荒野之狼))是瑞士籍作家赫尔曼·黑塞(Hermann
Hesse)所创作的长篇小说
。《荒原狼》是黑塞中期创作之代表作,亦是外做生涯被的里程碑。《荒原狼》通过对私有精神疾患之讲述,展示起现代社会面临人性中分裂的苦果。无家可归的哈勒尔,像相同止狼一样给无情追猎,被精神疾病折磨。哈勒尔以同赫尔米娜、帕布洛、玛丽亚等几乎独第一人士中的相互接触蒙走向了人生的两难,陷入了人命之深渊;最终他而起歌德、莫扎特等“不朽者”的崇高思想中获取启迪,摆脱绝望,重新赶回现实生活。小说幻想色彩浓郁,象征意味深远,被号称德国底《尤利西斯》。
赫尔曼·黑塞,1946年诺贝尔文学奖获得者。

科学 3

Der Steppenwolf(也翻作荒野之狼)

缓存和可伸缩性

  通过以网层级消除通过远距离调用来取请求的多寡,缓存提高了网的而是扩展性。服务通过以响应中安装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

《杂草的故事》

《杂草的故事》是2015年译林出版社出版的书,作者是[英]理查德·梅比。杂草是某种类型的植物还是一样种人类的思索?它们是生物种或者文化的结果?它们为何有?如果没有她,世界将会怎么样?英国博物学作家理查德·梅比讲述了以人类同自然的决斗过程中,四处漂泊的野草是什么给定义、被诠释、被限制与受不公平地对待,又是哪突围文明的界线并影响人类对自然之意。理查德·梅比一方面为天体不让待见的植物辩护,一方面打历史、小说、诗歌、戏剧和民间故事中钩沉杂草同人类推不断理还乱之关联。文明背后的野性从未走远,一总理立足英国本土的杂草变迁史,却写出全球化视野中相同轴包罗万象的野生植物迁徙与狂欢的图景。

科学 4

四处漂泊的荒草是如何吃定义

传安全

  所有的求证都当采取SSL。OAuth2需要授权服务器和access
token(访问令牌)来使用TLS(安全传输层协议)。

  以HTTP和HTTPS之间切换会带来平安隐患,最好之做法是享有简报默认都施用TLS。

她干的几乎论书籍非常正确:

德国女作家赫尔曼黑塞的作品《荒原狼》——接受不周全和谐;《悉达多》接受不周到的世界;

截至自己上高中的一个下午,读到赫尔曼·黑塞底《荒原狼》,其中起相同段落话“因为自同你同样。因为自啊和而同一孤独,和而一样未能够便于生,不克好人,不克好我自己,我莫可知严肃认真地比生活,对待别人和协调。世上总有几只这么的人口,他们本着生存要求很高,对自己之笨拙和粗暴又不甘心。”
                                                                     
                                                               
 ——蒋方舟新浪博客

暨植物相关的修:

《植物的私欲》——新鲜的植物视角,植物诱惑引导人类,看人类发展史;

《杂草的故事》——杂草看人类;

诙谐之题:

美国作家 比尔布莱森 《万物简史》《趣味生活指南》

保护服务的安

《植物的欲念》

《植物的欲望》一书中,畅销书作者迈克尔·波伦讲述了关于四种日常植物的一部分可爱的故事,这四种植植物包含了人类和天地的无限重要的一点联系。

=

科学 5

至于四种植日常植物的部分喜闻乐见的故事

破坏性的改动

  • 改变属性名(例如将”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资源的链接给移除。

  虽然上面列有之并无圆满,但它被闹了一部分碰头针对客户端有破坏性影响的转变类型,这时急需考虑提供一个新资源或新本子。

《悉达多》

黑塞的第九管辖作品,1922年以德国出版,通过对所有者公悉达多身上的少只“自我”——理性之最好的“自我”和感的个别的“自我”——的抒写,黑塞探讨了个体怎么在少的性命受到追求极致的、永恒的人生境界的问题。读者从中既可以观测作家对性的慈和敬畏,对人生与大自然的满睿智的了解,又能够感受及外针对性人情的人道主义理想的呼叫和敬仰,同时,还足以理解到当西方人的作者对东尤其是礼仪之邦想智慧之纳以及借鉴。

科学 6

弃用

  Deprecated(弃用)的目的是用来验证资源对API仍然可用,但当前会不存并更换得无可用。小心:弃用的时长将由弃用政策决定——这里并无吃有概念。

昨夜之前,对于蒋方舟一无所知。当自身望海报主题讲的是文艺女青年之本身修养时,并非有兴趣。然而以无意识中任了58分钟29秒的话音之后,我发现其是一个要命怪的人数。她即使年轻但是内心成熟而快,她未爱鸡汤化为功学专爱描写失败的人。她开中所关联的逃离,让人口感同身受。而现实的她可是追求现实的食指。

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

资源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

日期/时间处理

  如果没妥善地、一致地拍卖好日期与时吧,这将变为一个颇累。我们常会遇见时区的题材,而且由于日期在JSON中凡为字符串的格式在的,如果无指定统一的格式,那么解析日期为会是一个问题。

  在接口内部,服务端应该为UTC或GMT时间来存储、处理及缓存时间戳。这将使得解决日期与时间之题目。

  用Content-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>

  传安全

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

  并不需要在每一个求中还指定版本号。由于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”}

HTTP状态码(前10)

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(未找到)。

 

  哟时应该创建一个初本子?

  由此内容商支持版本管理

REST是什么?

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

  六单计划则分别是:

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

  以下是这些规划则的事无巨细讨论:

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。

    支持CORS

  DELETE

过滤

  在本文中,过滤被定义为“通过一定的准来确定要要返回的数额,从而减少返回的多少”。如果服务端支持一学完整的较运算符和复杂的规范相当,过滤操作以移得相当复杂。不过我们一般会采取部分概括的表达式,如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)。

REST快速提示

外加资源

    为此字符串查询参数进行限制

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

 

  Body内容中之日期/时间序列化

  复数

网站

  http://www.restapitutorial.com
http://www.toddfredrich.com
  http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
  http://www.json.org/
https://github.com/tfredrich/DateAdapterJ
  http://openid.net/developers/specs/
  http://oauth.net/documentation/spec/
  http://www.json.org/JSONRequest.html
http://labs.omniti.com/labs/jsend
  http://enable-cors.org/
  http://www.odata.org/documentation/uri-conventions#FilterSystemQueryOption
  http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
  https://developer.linkedin.com/apis
  http://developers.facebook.com/docs/reference/api/
  https://dev.twitter.com/docs/api
http://momentjs.com/
  http://www.datejs.com/

 

当原来翻译的功底及通过改:http://blog.csdn.net/huayuqa/article/details/62237010

英文原稿下载:RESTful Best Practices-v1
2.pdf

资源命名

  除了当地使用HTTP动词,在开立一个方可知晓的、易于使的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:

日期/时间拍卖

C-S架构

  统一接口使得客户端与服务端相互分开。关注分离意味什么?打只假设,客户端不欲仓储数据,数据都留于服务端内部,这样使客户端代码的可移植性得到了提升;而服务端不需考虑用户接口和用户状态,这样一来服务端将进而简便易行好拓展。只要接口不移,服务端和客户端可单独地开展研发与替换。

分页

  上述方法通过请求方指定数据集的限定来界定返回结果,从而实现分页功能。上面的例子中一共发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/**

REST快速提示

  (根据地方提到的六个条件)不管在技术上是无是RESTful的,这里有一部分好像REST概念的建议。遵循它,可以实现重新好、更使得之劳务:

招来有支持的版本

版本控制应于啊级别出现?

  建议对单个的资源拓展版本控制。对API的组成部分改观,如修改工作流,也许如果逾多个资源的版本控制,以这来防止对客户端起破坏性的影响。

  分页

  应用HTTP动词表示有意思

  应用程序安全

HTTP动词

可缓存

  于万维网上,客户端好缓存页面的应内容。因此应都许诺隐式或显式的定义为可缓存的,若不足缓存则要避免客户端在反复求后之所以旧数据要污染数据来响应。管理得当的休养存会部分地还是全地除了客户端与服务端之间的并行,进一步改良性及延展性。

设想连通性

  REST的原理之一即是并通性——通过超媒体链接实现。当当响应中回到链接时,api变的更兼具从描述性,而在无其常服务端依然可用。至少,接口本身可以呢客户端提供哪些寻找数据的参考。此外,在通过POST方法创建资源时,还可应用头位置包含一个链接。对于响应中支持分页的联谊,”first”、
“last”、”next”、和”prev”链接至少是很管用之。

 

询问,过滤和分页

带有Content-Type的链接

  Atom风格的链接支持”type”属性。提供足够的信息以便客户端可针对特定的本与内容类型进行调用。

  装进响应

支持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'}")

 

    最为小化链接推荐

极致小化链接推荐

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

  对于自服务端返回的表征集合,每个表征应该以它们的链接集合中携带一个最好小的“自身”链接属性。为了便于分页操作,其它的链接可以放在一个独的链接集合中回到,必要常常可分包“第一页”、“上等同页”、“下一致页”、“最后一页”等信息。

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

    链接格式

  ETag Header

  PUT和POST的创始于

透过情节商支持版本管理

  以往,版本管理通过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”}

劳动版本管理

    经过特色来操作资源

  基于资源

  不同资源需要因此URI来唯一标识。返回给客户端的风味和资源本身在概念上有所不同,例如服务端不会见一直传送一个数据库资源,然而,一些HTML、XML或JSON数据可知亮部分数据库记录,如用芬兰语来发表还是用UTF-8编码则使根据请求与服务器实现之底细来支配。

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作为响应。在其深受全淘汰之前,这是终极一个不过于肯定的地方。

    过滤

幂等性

  不要从字面意思来掌握啊是幂等性,恰恰相反,这和一些功能紊乱的天地无关。下面是根源维基百科的说:

以电脑科学中,术语幂相当用于更周全地讲述一个操作,一软还是数履该操作发生的结果是千篇一律的。根据使用的上下文,这恐怕出差之含义。例如,在方要子例程调用有副作用的情景下,意味着当率先调用之后为改的状态为保无换。

  从REST服务端的角度来拘禁,由于操作(或服务端调用)是幂等的,客户端好为此更的调用而有同样之结果——在编程语言中操作像是一个”setter”(设置)方法。换句话说,就是采取多独一样的请与运单个请求效果一样。注意,当幂等操作以服务器上发出同样之结果(副作用),响应本身也许是见仁见智之(例如当差不多个请求中,资源的状态恐怕会见改变)。

  PUT和DELETE方法吃定义为凡幂等的。查看http请求中delete动词的警戒信息,可以参照下文的DELETE部分。GET、HEAD、OPTIO和TRACE方法从被定义也安全的不二法门后,也吃定义也幂等的。参照下关于安全的段落。

  XML和JSON

  POST

  C-S架构

  版本控制应于啊级别出现?

定义

  自描述的消息

  每条信息都含有足够的数额用于确认消息该怎么处理。例如要出于网络媒体类型(已领略的使MIME类型)来确认要调用哪个解析器。响应同样也表明了它的缓存能力。

授权

  对劳动的授权和针对性其它应用程序的授权一样,没有其它区别。它根据这样一个题材:“主体是否针对加的资源起求的许可?”这里叫起了简便易行的老三起数据(主体,资源同准),因此很容易构造一个支持这种概念的授权服务。其中核心是为与资源访问许可的总人口或者系。使用这些相似概念,就足以呢各一个主题构建一个缓存访问控制列表(ALC)。

    弃用

  无状态

HTTP动词

  Http动词主要按“统一接口”规则,并提供被我们相应之因名词的资源的动作。最重点要最好常用之http动词(或者称方法,这样叫可能更恰当些)有POST、GET、PUT和DELETE。这些分别对应于创建、读取、更新和去(CRUD)操作。也时有发生为数不少另的动词,但是下频率比较小。在这些下于少之艺术吃,OPTIONS和HEAD往往采用得重新多。

非破坏性的改动

  • 当回到的JSON中上加新属性
  • 增长指向任何资源的”link”
  • 添加content-type支持的新格式
  • 添加content-language支持之初格式
  • 由API的创建人和消费者都使处理不同的casing,因此casing的更动无关紧要

    自打描述的音讯

旁系统

  客户端通常无法表明自己是直或间接与端服务器进行连接。中介服务器可以通过启用负载均衡或供共享缓存来提升系统的延展性。分层时同样要考虑安全策略。

  客观的资源名

哎时该创建一个初本子?

  API开发中之不少面还见面打破约定,并最终指向客户端有有不良影响。如果你莫确定API的修改会带怎么样的后果,保险起见最好考虑采取本控制。当您于考虑提供一个初本子是否适宜时,或者考虑针对现有的回到表征进行改动是否必然能够满足急需并于客户端所领时,有这样几独元素而考虑。

  处理跨域问题

处理跨域问题

   我们还听说过关于浏览器的同源策略要同源性需求。它借助的凡浏览器只能请时在显示的站点的资源。例如,如果手上着显示的站点是www.Example1.com,则该站点不能够针对www.Example.com倡议呼吁。显然这会潜移默化站点访问服务器的办法。

  时发有限单受大面积接受的支持跨域请求的不二法门:JSONP和跨域资源共享(CORS)。JSONP或“填充的JSON”是平种植使模式,它提供了一个法要来自不同域中之服务器的数。其工作方法是于服务器返回任意的JavaScript代码,而休是JSON。客户端的响应由JavaScript解析器进行分析,而非是直接解析JSON数据。另外,CORS是同样种web浏览器的技艺专业,它为web服务器定义了相同种植方法,从而允许服务器的资源得以于无同域的网页访问。CORS被当是JSONP的摩登替代品,并且可被抱有现代浏览器支持。因此,不建议采用JSONP。任何动静下,推荐选择CORS。

  资源通过链接的而是发现性(HATEOAS续)

  幂等性

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)
—— 当服务器抛来异常时,捕捉到之貌似错误。

 

创建适当粒度的资源

  同开始,系统被法底层应用程序域或数据库架构的API更易给创造。最终,你晤面要用这些劳务都整合及一头——利用基本上宗底层资源减少通信量。在创造独立的资源后再次创更老粒度的资源,比从更怪之联手集中创建于充分粒度的资源更是便于有。从有粗之容易定义的资源开始,创建CRUD(增删查改)功能,可以要资源的创立变得又易于。随后,你可以创造这些根据用例和压缩通信量的资源。

动HTTP动词表示有含义

  任何API的使用者能发送GET、POST、PUT和DELETE请求,它们非常非常程度明显了所吃告的目的。同时,GET请求不能够转任何秘密的资源数量。测量与钉仍可能有,但只有见面更新数据如果未会见更新由URI标识的资源数量。

  资源URI示例

结果的过滤跟排序

  针对返回结果,还索要考虑如何在服务端对数码进行过滤跟排,以及如何按照指定的顺序对子数据进行查找。这些操作可以跟分页、结果限制,以及字符串查询参数filter和sort等互相结合,可以兑现强的数据检索功能。

  再强调平等不行,过滤和排序都是繁体的操作,不欲默认提供给所有的资源。下文将介绍如何资源要提供过滤与排序。

身份验证

  时极好之做法是用OAuth身份验证。强烈推荐OAuth2,不过它依旧处在草案状态。或者选择OAuth1,它完全好胜任。在好几情况下也可择3-Legged
OAuth。更多关于OAuth的业内好查看此http://oauth.net/documentation/spec/。

  OpenID是一个增大选择。不过建议以OpenID作为一个外加的身份验证选项,以OAuth为主。更多关于OpenID的标准好查此http://openid.net/developers/specs/。

缓存和可伸缩性

POST

  POST请求时给用来创造新的资源,特别是叫用来创造于属于资源。从属于资源就属为任何资源(如大资源)的资源。换句话说,当创建一个新资源时,POST请求发送给父资源,服务端负责用新资源及爸爸资源开展关联,并分配一个ID(新资源的URI),等等。

  例如:

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

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

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

正文主要读者

REST是什么

安全

  来自维基百科:

一对办法(例如GET、HEAD、OPTIONS和TRACE)被定义也安全之道,这意味着它不过于用于信息寻找,而非可知改服务器的状态。换句话说,它们不见面发副作用,除了相对来说无害的熏陶使日志、缓存、横幅广告要计数服务等。任意的GET请求,不考虑用状态的上下文,都深受当是高枕无忧之。

  总之,安全意味着调用的方不见面挑起副作用。因此,客户端可数用安全的恳求而休用担心对服务端产生其它副作用。这表示服务端必须信守GET、HEAD、OPTIONS和TRACE操作的平安概念。否则,除了针对消费端产生模糊外,它还会造成Web缓存,搜索引擎以及任何活动代理的题材——这将于服务器上起意想不到的结局。

  根据定义,安全操作是幂等的,因为它在服务器上发同样之结果。

  安全之方吃实现呢特念操作。然而,安全并无代表服务器必须每次都回去相同之应。

 

复数

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

  在你的层级结构中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是实用的。好吧…

 

    本身当以支持小只版?

基于范围之应

  对一个因范围之请来说,无论是通过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工具或未支持该符号。

 

书籍

  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.

    因范围之应

劳版本管理

   坦率地说话,一说及本就会让丁觉得格外困难,很麻烦,不顶好,甚至会见吃人当难受——因为马上会大增API的复杂度,并以可能会见针对客户端有一些震慑。因此,在API的宏图受到如果尽量避免多只不同之本子。

  不支持版本,不以版本控制作为糟糕的API设计之仗。如果您以APIs的计划性受到引入版本,这迟早且见面叫您捉狂。由于返回的数目通过JSON来见,客户端会由于不同之版要收及不同的特性。这样就见面在有的题材,如由内容我及说明规则者改变了一个早就存在的性质的意义。

  当然,我们无能为力避免API可能于一些时段用变更返回数据的格式和内容,而及时为将招致消费端的有的转变,我们应该避免进行有主要的调动。将API进行版本化管理是免这种根本变更之一模一样栽有效方法。

引言

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

  字符串查询参数为当作Range
header的替代选择,它利用offset和limit作为参数叫做,其中offset代表要询问的第一久记下编号(与上述的用来范围标记的items第一独数字相同),limit代表记录之极致要命条数。下面的事例返回的结果以及上述用范围标记的例证一样:

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

  Offset参数的价值与Range
header中的切近,也是从0开始计算。Limit参数的值是归记录的极度老数目。当字符串查询参数中未指定limit时,服务端应当于来一个缺省之无比特别limit值,不过这些参数的用还得以文档中开展说明。

定义

护服务的安

  Authentication(身份证明)指的凡确认给定的呼吁是自服务业已领略的某(或某个系统)发出之,且请求者是外协调所声明的那个人。Authentication是以求证请求者的实事求是身份,而authorization(授权)是为证明请求者有权力去执行于求的操作。

  本质上,这个过程是这般的:

  1. 客户端发起一个要,将authentication的token(身份证明令牌)包含在X-Authentication
    header中,或者将token叠加以请的查询串参数中。
  2. 服务器对authorization
    token(授权令牌)进行反省,并展开求证(有效且未过),并冲令牌内容分析或者加载认证中心。
  3. 服务器调用授权服务,提供证明中心、被呼吁资源与必备之操作许可。
  4. 倘授权通过了,服务器将会见延续健康运转。

  上面第三步之开销可能会见比较深,但是如果如果有一个而缓存的权柄控制列表(ACL),那么在有远程请求前,可以于该地创建一个授权客户端来缓存最新的ACLs。

  安全

叠加资源

    自我争告客户端给弃用的资源?

正文主要读者

  该最佳实践文档适用于对RESTful
Web服务感兴趣之开发人员,该服务呢超多独劳务之零部件提供了于高的可靠性和一致性。按照本文的点拨,可快捷、广泛、公开地为内外部客户采用。

  本文中之指导标准一致适用于工程师们,他们希望用这些根据最佳实践标准开发的劳务。虽然他们越是关心缓存、代理规则、监听和平安等连锁方,但是该文档能作为一如既往卖包含所有品种服务的总指南。

  另外,通过由这些点原则,管理人员了解及开创公共的、提供高稳定的服务所待花的全力,他们也可是从中受益。

 

  身份验证

排序

  排序决定了由服务端返回的记录的次第。也就算是本着响应中的多漫长记下进行排序。

  同样,我们这里仅考虑有比较简单的气象。推荐使用排序字符串查询参数,它富含了一致组用分隔符分隔的属于性名。具体做法是,默认对每个属性名以升序排列,如果属于性名有前缀”-“,则仍降序排列。用竖线(”|”)分隔每个属性名,这与前边过滤效果受到之参数名/值对之做法无异于。

  举个例子,如果我们怀念按部就班用户之姓氏和叫展开升序排序,而对雇佣时间开展降序排序,请求将是这么的:

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

  再次强调一下,查询参数名/值对被之属性名要和服务端返回的性能名相匹配。此外,由于排序操作比较复杂,我们惟有对急需之资源提供排序功能。如果需要的话也可以在客户端对小之资源集聚进行排列。

 

链接格式

  参照整个链接格式的正经,建议遵守一些好像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

本身哪告客户端给弃用的资源?

  许多客户端将来看的资源或在新本子引入后会叫废弃掉,因此,他们待发出同一种艺术来发现同督查他们之应用程序对委用资源的施用。当呼吁一个弃用资源时,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”}

 

故范围标记进行限定

  当用HTTP header而未是字符串查询参数来博记录的克时,Ranger
header应该经过以下内容来指定范围: 

  Range: items=0-24

  注意记录是从0开始的接连字段,HTTP规范被证明了哪利用Range
header来请求字节。也就是说,如果一旦请数据汇总之第一久记下,范围应该从0开始算从。上述的请将会晤回来前25单记录,假要数据汇总至少有25长记下。

  而当服务端,通过检查请求的Range
header来确定该归哪些记录。只要Range
header存在,就会有一个简短的正则表达式(如”items=(\d+)-(\d+)”)对那进展辨析,来得到要物色的范围值。

  分系统

返回表征

求不支持的版本

  当呼吁一个不支持的版本号时(包含在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”]

    排序

理所当然之资源名

  合理之资源名称或者路径(如/posts/23如果休是/api?type=posts&id=23)可以再次明了一个伸手的目的。使用URL查询串来过滤数据是充分好的法,但未应用于固定资源名称。

  适当的资源名称也服务端请求提供上下文,增加服务端API的可理解性。通过URI名称分层地查看资源,可以于使用者提供一个协调的、容易理解的资源层次,以在他们的应用程序上运。资源名称应当是名词,避免吗动词。使用HTTP方法来指定要的动作有,能为工作越的明明白白。

返表征

  正使前方提到的,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,它概括容易读,没有模式及命名空间的克,换句话来说是凭正规的,易于解析。

    故此范围标记进行限定

按需编码(可选)

  服务端通过传输可实施逻辑给客户端,从而为该现拓展及定制功能。相关的事例有编译组件Java
applets和客户端脚本JavaScript。

  遵从上述标准,与REST架构风格保持一致,能让各种分布式超媒体系统具备梦想之自然属性,比如高性能,延展性,简洁,可变性,可视化,可移植性和可靠性。

  提示:REST架构中的计划则遭到,只有按需编码为可卜项。如果有服务违反了任何随意一件则,严格意思上不克称之为RESTful风格。

 

  PUT

应用程序安全

  对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密钥存储在加密的安密钥库中。

 

  GET

    非破坏性的改动

  通过特征来操作资源

  当客户端收到包含元数据的资源的风味时,在起权力的景况下,客户端都控制的足的消息,可以针对劳动端的资源进行删改。

  资源命名的反例

  检索来支持之本子

PUT和POST的创立于

  总之,我们建议采用POST来创造资源。当由客户端来控制新资源有着哪些URI(通过资源名称或ID)时,使用PUT:即如果客户端知道URI(或资源ID)是呀,则指向该URI使用PUT请求。否则,当由服务器或服务端来控制创办的资源的URI时虽然动用POST请求。换句话说,当客户端在开创之前不理解(或无法知晓)结果的URI时,使用POST请求来创造新的资源。

  网站

询问,过滤与分页

  对于大数据集,从带宽的角度来拘禁,限制返回的数据量是深主要之。而起UI处理的角度来拘禁,限制数据量也一律任重而道远,因为UI通常只能展现大数量集中的等同粗有数据。在数据集的增长速度不确定的气象下,限制默认返回的数据量是杀有必要的。以Twitter为条例,要拿走有用户之推文(通过个人主页的时光轴),如果没特意指定,请求默认只会回去20长条记下,尽管系统最多得回到200长记下。

  除了限制返回的数据量,我们尚用考虑如何对命运据集进行“分页”或下拉滚动操作。创建数量的“页码”,返回大数目列表的曾清楚片段,然后标出数据的“前无异页”和“后同页”——这等同作为让名分页。此外,我们恐怕啊用指定响应中将包含哪些字段或性能,从而限制返回值的数额,并且我们愿意最后能透过一定值来进行询问操作,并对回值进行排序。

  有少数栽重点的办法来而限定查询结果及实践分页操作。首先,我们可成立一个目方案,它可坐页码为导向(请求被而被闹各个一样页的记录数及页码),或者为记录为导向(请求被一直为出第一修记下以及终极一条记下)来规定返回值的前奏位置。举个例子,这有限种植艺术分别表示:“给来第五页(假设每页有20长长的记下)的记录”,或“给起第100及第120长之笔录”。

  服务端将依据运作机制来拓展切分。有些UI工具,比如Dojo
JSON会选择模仿HTTP规范使用字节范围。如果服务端支持out of
box(即开箱即用力量),则前端UI工具及后端服务中间无需外移,这样用起来会坏有益。

  下文将介绍一种植方法,既能支持Dojo这样的分页模式(在伸手求头中让有记录之界定),也克支撑下字符串查询参数。这样一来服务端将转移得进一步灵敏,既可行使类Dojo一样先进的UI工具集,也得以用简易直接的链接和标签,而任由需还为之多复杂的付出工作。但一旦服务不直支持UI功能,可以考虑不要在伸手求头中吃有记录范围。

  要特别指出的凡,我们并无引进以具有服务中使查询、过滤和分页操作。并无是具备资源且默认支持这些操作,只有少数特定的资源才支撑。服务与资源的文档应当说明什么接口支持这些扑朔迷离的效果。

动用Content-Location来增长响应

  可选。见RDF(Resource Description Framework,即资源描述框架)规范。

  创办适当粒度的资源

  带有Content-Type的链接

    超媒体即祭状态引擎(HATEOAS)

无状态

  正如REST是REpresentational State
Transfer的缩写,无状态十分关键。本质上,这标志了处理要所急需的状态已经包含在呼吁我里,也产生或是URI的一致片段、查询串参数、body或头部。URI能够唯一标识每个资源,body中吗带有了资源的转态(或转态变更情况)。之后,服务器将展开拍卖,将相关的状态或资源通过头部、状态与响应body传递让客户端。

  从事我们立马同一业的多数人犹习惯使用容器来编程,容器被生一个“会话”的定义,用于在差不多只HTTP请求下保持状态。在REST中,如果要是以差不多个请求下维持用户状态,客户端必须概括客户端的有着信息来好请求,必要常常重发送请求。自从服务端不待保障、更新或传递会话状态后,无状态性得到了更甚之延展。此外,负载均衡器无需担心与无状态系统里的对话。

  所以状态及资源中发生啊区别?服务器对状态,或者说是应用状态,所关切的触发是以眼前对话或请被如形成请求所需要的数。而资源,或者说是资源状态,则是概念了资源特色的数码,例如存储于数据库被的数额。由此可见,应用状态是是乘客户端以及请的改观如果反的多寡。相反,资源状态对于发出请求的客户端的话是免换的。

  以网络采用之有同特定岗位及摆一个回来按钮,是因其仰望您可知随自然的逐一来操作也?其实是盖其违反了任状态的口径。有很多非信守无状态原则的案例,例如3-Legged
OAuth,API调用速度限制等。但还是要尽量确保服务器遭受不需要在差不多只请求下维持以状态。

  按需编码(可选)

资源通过链接的而是发现性(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请求返回集合,对于有分页的事态后我们见面提到。

  书籍

    破坏性的改动

  授权

  结果的过滤与排序

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暴露不安全的操作——它应有永远都非克改服务器上的外资源。

  集合接口

  告不支持之版

资源命名

  设想连通性

支持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/。

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

    据悉资源

自己应该而且支持小只本子?

  维护多个不同之版会吃工作易得烦、复杂、容易错,而且代价高,对于其它给定的资源,你应当支持非越2个本子。

结果限制

  “给起第3至第55条的笔录”,这种求数据的措施和HTTP的字节范围规范更平等,因此我们好据此她来标识Range
header。而“从第2漫长记下开始,给有极多20漫漫记下”这种艺术再次爱阅读和清楚,因此我们通常会就此字符串查询参数的法门来表示。

  综上所述,推荐既支持以HTTP Range
header,也支撑下字符串查询参数——offset(偏移量)和limit(限制),然后于服务端对响应结果进行限。注意,如果还要支持这有限种方法,那么字符串查询参数的优先级要逾Range
header。

  这里您恐怕会见来只问题:“这半栽方式效果相似,但是回去的数额不完全一致。这会无会见于人歪曲呢?”恩…就是有限个问题。首先使回的凡,这实在会被丁歪曲。关键是,字符串查询参数看起越清晰易懂,在构建与剖析时尤其便利。而Range
header则再度多是出于机械来以(偏向于底层),它进一步吻合HTTP使用正式。

  总之,解析Range
header的行事会多复杂度,相应的客户端在构建请求时也需开展部分甩卖。而利用单独的limit和offset参数会愈来愈容易懂和构建,并且不待对开发人员有再度多之渴求。

    支持JSONP

资源命名的反例

  前面我们都讨论了部分正好的资源命名的例子,然而有时有反面的例证吗特别有教育意义。下面是一些请勿极端具有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”指的是一个资源也?因此,这里我们费些口舌也是愿意你可知亮……

  结果限制

引言

  现今就起大量关于RESTful
Web服务至上实践的连带资料(详见本文最后的连锁文献有)。由于撰文之时空不同,许多资料遭受的情节是矛盾的。此外,想使经查文献来询问这种服务之上进是无极端长的。为了打探RESTful这无异定义,至少需要查阅三顶五据有关文献,而本文将能拉您加速这同样过程——摒弃多余的座谈,最大化地提炼出REST的极品实践与专业。

  与其说REST是一律仿照标准,REST更像是一致栽口径的集纳。除了六个根本之极外即没外的业内了。实际上,虽然有所谓的“最佳实践”和正规,但这些事物还跟教斗争一样,在持续地演变。

  本文围绕REST的广阔问题提出了意以及仿食谱式的议论,并由此介绍一些简约的背景知识对创建真实处境下的事先生产条件中一样的REST服务提供文化。本文收集了来自外渠道的音,经历过一次次的砸后不断改进。

  但于REST模式是否肯定比SOAP好用本时有发生比充分争(反之亦然),也许在一些情况下仍待创造SOAP服务。本文在提及SOAP时并未花较生篇幅来谈谈其的相对优点。相反由于技术同行在不断进步,我们用延续坚持我们的比方–REST是随即统筹web服务之特等方式。

  第一组成部分概述REST的含义、设计则和它的不同寻常的处在。第二有些罗列了一些小贴士来记忆REST的劳务意见。之后的有些则会又透彻地吧web服务创建人员提供一些细节之支撑与议论,来促成一个能够公开亮在生产条件受到之强质量REST服务。