RESTful服务至上实践

本文重要读者

引言

REST是什么

  合并接口

    依照财富

    透过特色来操作能源

    自描述的消息

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

  无状态

  可缓存

  C-S架构

  分层系统

  按需编码(可选)

REST火速提醒

  运用HTTP动词表示一些意思

  成立的能源名

  XML和JSON

  创办适当粒度的能源

  设想连通性

定义

  幂等性

  安全

HTTP动词

  GET

  PUT

  POST

  PUT和POST的开创相比较

  DELETE

财富命名

  资源URI示例

  能源命名的反例

  复数

回去表征

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

    小小的化链接推荐

    链接格式

  装进响应

  拍卖跨域难题

    支持CORS

    支持JSONP

询问,过滤和分页

  结果限制

    用范围标记举行限制

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

    遵照范围的响应

  分页

  结果的过滤和排序

    过滤

    排序

服务版本管理

  经过剧情协商扶助版本管理

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

  呼吁不援救的版本

  如曾几何时候应该成立二个新本子?

    破坏性的修改

    非破坏性的修改

  版本控制应在怎么样级别出现?

  采纳Content-Location来增加响应

  带有Content-Type的链接

  找出支持的本子

    自家应当同时帮助几个版本?

    弃用

    自作者怎么样告知客户端被弃用的能源?

日期/时间拍卖

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

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

保证服务的平凉

  身份验证

  传输安全

  授权

  应用程序安全

缓存和可伸缩性

  ETag Header

HTTP状态码(前10)

叠加能源

  书籍

  网站

 

本文重要读者

  该最佳实践文书档案适用于对RESTful
Web服务感兴趣的开发人士,该服务为跨多少个劳务的机件提供了较高的可信赖性和一致性。遵照本文的点拨,可飞快、广泛、公开地为内外部客户使用。

  本文中的教导原则一致适用于工程师们,他们希望利用那一个依照最佳实践标准开发的服务。固然她们一发爱惜缓存、代理规则、监听及康宁等息息相关地点,然而该文书档案能作为一份包括全体品种服务的总指南。

  其它,通过从那一个指引标准,管理人士驾驭到开创公共的、提供高稳定的服务所需花费的不竭,他们也可从中收益。

 

引言

  到现在已有雅量关于RESTful
Web服务至上实践的连带质感(详见本文最终的连锁文献部分)。由于撰文的小运各异,许多资料中的内容是争持的。此外,想要通过查看文献来询问这种劳动的开拓进取是不太可取的。为了理解RESTful这一概念,至少要求查阅三到五本有关文献,而本文将能够帮您加快这一经过——抛弃多余的座谈,最大化地提炼出REST的极品实践和标准。

  与其说REST是一套标准,REST更像是一种口径的集合。除了多个根本的标准外就没有其余的正式了。实际上,就算有所谓的“最佳实践”和规范,但这几个事物都和宗教斗争一样,在持续地演化。

  本文围绕REST的大规模难题提议了见识和仿食谱式的议论,并经过介绍部分回顾的背景知识对创设真实情形下的预生产条件中一致的REST服务提供文化。本文收集了来自其余渠道的音讯,经历过二次次的败诉后不断革新。

  但对此REST情势是还是不是必然比SOAP好用仍有较大争议(反之亦然),大概在一些境况下仍必要创制SOAP服务。本文在提及SOAP时并未花较大篇幅来谈谈它的顶牛优点。相反由于技术和行业在不断升高,大家将继续细水长流大家的要是–REST是当下规划web服务的特级艺术。

  第贰局地概述REST的含义、设计准则和它的尤其之处。第1片段列举了一些小贴士来回想REST的服务意见。之后的一些则会更深刻地为web服务成立职员提供部分细节的辅助和议论,来落到实处1个力所能及驾驭呈未来生产环境中的高品质REST服务。

 

REST是什么?

  REST架构格局讲述了各类设计准则。那几个用于架构的规划准则,最早是由罗伊菲尔德ing在他的学士散文中提议并定义了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内容、查询串参数、请求头和UPRADOI(财富名称)来传送状态。服务端通过body内容,响应码和响应头传送状态给客户端。那项技艺被喻为超媒体(或超文本链接)。

  除了上述内容外,HATEOS也象征,要求的时候链接也可被含有在回到的body(或底部)中,以提供U奇骏I来探寻对象自作者或关系对象。下文将对此开始展览更详尽的阐释。

  统一接口是每一种REST服务统一筹划时的画龙点睛准则。

无状态

  正如REST是REpresentational State
Transfer的缩写,无状态很首要。本质上,那标志了拍卖请求所需的情景已经包蕴在呼吁作者里,也有或然是URubiconI的一局地、查询串参数、body或底部。UOdysseyI能够唯一标识各样财富,body中也包涵了财富的转态(或转态变更情况)。之后,服务器将开始展览处理,将有关的图景或能源通过尾部、状态和响应body传递给客户端。

  从事我们这一行当的大多数人都习惯使用容器来编制程序,容器中有3个“会话”的概念,用于在多少个HTTP请求下维持状态。在REST中,假如要在八个请求下维持用户景况,客户端必须归纳客户端的有所新闻来形成请求,须求时再也发送请求。自从服务端不必要保证、更新或传递会话状态后,无状态性获得了更大的延展。其它,负载均衡器无需担心和无状态系统之间的对话。

  所以状态和财富间有哪些差距?服务器对于状态,恐怕说是应用状态,所关怀的点是在此时此刻对话或请求中要做到请求所需的数目。而财富,恐怕说是能源情状,则是概念了能源特色的数额,例如存储在数据库中的数据。不问可知,应用状态是是随着客户端和呼吁的变动而改变的多寡。相反,能源情形对于发出请求的客户端的话是不变的。

  在网络采纳的某一一定岗位上布署二个回到按钮,是因为它仰望您能按一定的一一来操作吗?其实是因为它违反了无状态的准绳。有广大不服从无状态原则的案例,例如3-Legged
OAuth,API调用速度限制等。但照旧要硬着头皮确认保障服务器中不供给在八个请求下保持利用状态。

可缓存

  在万维网上,客户端能够缓存页面包车型地铁响应内容。因而响应都应隐式或显式的定义为可缓存的,若不足缓存则要制止客户端在一而再呼吁后用旧数据或脏数据来响应。管理稳妥的缓存会部分地或完全地除了客户端和服务端之间的互动,进一步创新质量和延展性。

C-S架构

  统一接口使得客户端和服务端互相分开。关切分离意味什么?打个借使,客户端不须要仓库储存数据,数据都留在服务端内部,那样使得客户端代码的可移植性得到了提拔;而服务端不必要考虑用户接口和用户境况,那样一来服务端将越来越简约易拓展。只要接口不更改,服务端和客户端能够单独地拓展研究开发和替换。

分层系统

  客户端日常不只怕证明本人是平昔或然直接与端服务器进行连接。中介服务器能够通过启用负载均衡或提供共享缓存来提高系统的延展性。分层时同样要考虑安全策略。

按需编码(可选)

  服务端通过传输可进行逻辑给客户端,从而为其权且拓展和定制功用。相关的例子有编写翻译组件Java
applets和客户端脚本JavaScript。

  坚守上述标准,与REST架构风格保持一致,能让各样分布式超媒类别统有着梦想的自然属性,比如高质量,延展性,简洁,可变性,可视化,可移植性和可信赖性。

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

 

REST快捷提醒

  (依据地点提到的四个标准)不管在技术上是或不是RESTful的,那里有部分近乎REST概念的提出。遵守它们,可以达成更好、更使得的劳动:

采用HTTP动词表示一些意义

  任何API的使用者能够发送GET、POST、PUT和DELETE请求,它们非常大程度分明了所给请求的目标。同时,GET请求无法改变任何秘密的财富数量。衡量和跟踪仍也许发生,但只会更新数据而不会更新由UCR-VI标识的财富数量。

合理的能源名

  合理的财富名称恐怕路径(如/posts/23而不是/api?type=posts&id=23)能够更强烈一个呼吁的指标。使用U冠道L查询串来过滤数据是很好的方法,但不应有用于固定财富名称。

  适当的财富名称为服务端请求提供上下文,增添服务端API的可通晓性。通过UGL450I名称分层地查看能源,能够给使用者提供一个温馨的、简单驾驭的财富层次,以在他们的应用程序上应用。财富名称应当是名词,幸免为动词。使用HTTP方法来内定请求的动作部分,能让工作更是的明精通白。

XML和JSON

  提出暗中同意帮衬json,并且,除非花费很震惊,不然就同时援助json和xml。在地道图景下,让使用者仅透过转移扩充名.xml和.json来切换类型。其余,对于支撑ajax风格的用户界面,三个被卷入的响应是老大有帮扶的。提供2个棉被服装进的响应,在暗许的依然有单独扩大名的景观下,例如:.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服务端的角度来看,由于操作(或服务端调用)是幂等的,客户端能够用重新的调用而发出相同的结果——在编制程序语言中操作像是3个”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)请求仅用于读取数据而不转移多少。因而,那种使用方法被认为是平安的。相当于说,它们的调用没有数据修改或污染的风险——调用3次和调用十一遍照旧尚未被调用的功效一样。其它,GET(以及HEAD)是幂等的,那意味着使用八个一律的伸手与使用单个的请求最后都拥有相同的结果。

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

PUT

  PUT日常被用来立异能源。通过PUT请求八个已知的能源U昂科雷I时,须求在呼吁的body中带有对原有能源的立异数据。

  但是,在财富ID是由客服端而非服务端提供的情形下,PUT同样能够被用来创立财富。换句话说,如果PUT请求的U本田UR-VI中蕴藏的能源ID值在服务器上不存在,则用来创设能源。同时呼吁的body中必须含有要创制的财富的数据。有人认为那会发出歧义,所以唯有真的须求,使用那种情势来创制财富应该被慎用。

  或然大家也足以在body中提供由客户端定义的财富ID然后使用POST来创造新的财富——即便请求的U兰德宝马X5I中不带有要创制的能源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请求平时被用来创设新的财富,越发是被用来制造从属财富。从属财富即归属于其余财富(如父能源)的能源。换句话说,当创造2个新能源时,POST请求发送给父财富,服务端负责将新能源与父资源拓展关联,并分配二个ID(新能源的UPAJEROI),等等。

  例如:

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

  当创立成功时,重临HTTP状态码201,并顺便一个岗位头消息,在那之中带有指向开首创制的财富的链接。

  POST请求既不是高枕无忧的又不是幂等的,由此它被定义为非幂等质量源请求。使用八个一样的POST请求很或者会促成创立七个饱含相同音讯的财富。

PUT和POST的创导比较

  不问可见,我们提出选拔POST来创制财富。当由客户端来支配新财富有着何等U酷路泽I(通过能源名称或ID)时,使用PUT:即借使客户端知道UGL450I(或能源ID)是如何,则对该U安德拉I使用PUT请求。否则,当由服务器或服务端来决定创办的财富的U帕杰罗I时则应用POST请求。换句话说,当客户端在开立在此之前不明了(或无法精晓)结果的UOdysseyI时,使用POST请求来创制新的财富。

DELETE

  DELETE很简单了然。它被用来依据UTucsonI标识删除财富。

  例如:

  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操作是幂等的。假诺你对3个资源拓展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时,能源命名能够说是最具有争议和最根本的概念。2个好的财富命名,它所对应的API看起来更直观并且易于使用。相反,如若命名不好,同样的API会令人觉得很迟钝并且难以通晓和应用。当您要求为您的新API创造资源U凯雷德L时,那里有一些小技巧值得借鉴。

  从精神上讲,三个RESTFul
API最后都得以被回顾地作为是一堆U宝马7系I的集聚,HTTP调用这个UXC90I以及一些用JSON和(或)XML表示的能源,它们中有广大暗含了互相关系的链接。RESTful的可寻址能力根本借助U帕杰罗I。各个能源都有本身的地方或U奔驰M级I——服务器能提供的每三个立竿见影的音信都得以作为财富来公开。统一接口的尺度部分地通过ULacrosseI和HTTP动词的组成来解决,并符合利用规范和预订。

  在支配你系统中要利用的能源时,使用名词来命名这个财富,而不是用动词或动作来定名。换句话说,三个RESTful
UTucsonI应该提到到二个有血有肉的资源,而不是事关到三个动作。其它,名词还有着部分动词没有的特性,那也是另1个明了的成分。

  一些能源的例证:

  • 系统的用户
  • 学员注册的教程
  • 二个用户帖子的日子轴
  • 关爱别的用户的用户
  • 一篇有关骑马的小说

  服务套件中的每一种能源最少有贰个U大切诺基I来标识。若是这么些U帕杰罗I能表示一定的含义并且能够充裕描述它所表示的财富,那么它正是一个最好的命名。UEscortI应该有所可预测性和分层结构,那将力促增高它们的可驾驭性和可用性的:可预测指的是资源应该和名称保持一致;而分层指的是数量颇具关系上的结构。那并非REST规则或正式,不过它加重了对API的概念。

  RESTful
API是提须要消费端的。U宝马X5I的称号和结构应当将它所发表的意思传达给买主。平常大家很难知晓数据的界线是怎么着,不过从你的数目上你应当很有可能去品味找到要回到给客户端的数额是什么样。API是为客户端而陈设的,而不是为您的多少。

  借使大家今后要讲述三个包涵客户、订单,列表项,产品等职能的订单系统。考虑一下大家该怎么来讲述在那几个服务中所涉及到的能源的UTiguanIs:

资源URI示例

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

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

 

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

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

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

 

  上面是对成品有关的UENCOREI的片段提议:

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

  用于成立新的成品。

 

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

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

 

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

  一种方案是:

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

  那种格局能够用来创设订单,但贫乏相应的用户数量。

  

  因为大家想为用户创设3个订单(注意之间的关系),那一个UENCOREI大概不够直观,上面那么些URAV4I则更清楚一些:

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

  现在我们精晓它是为编号33245的用户创设一个订单。

 

  那下边那个请求重返的是怎样吧?

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

  只怕是3个号码为33245的用户所创办或享有的订单列表。注意:大家得以遮挡对该U汉兰达I进行DELETE或PUT请求,因为它的操作对象是贰个集聚。

 

  继续深刻,那下边那个U陆风X8I的伸手又象征怎么着呢?

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

  只怕是(为编号33245的用户)扩展贰个号码为8769的订单条目。没错!固然应用GET方式呼吁那几个ULacrosseI,则会重返那几个订单的有所条条框框。可是,即便这几个条款与用户消息非亲非故,大家将会提供POST
www.example.com/orders/8769/lineitems
这个URI。

  从重临的这一个条款来看,钦命的财富也许会有多个ULX570Is,所以大家兴许也亟供给提供这样3个URubiconI
GET
http://www.example.com/orders/8769
,用来在不通晓用户ID的事态下基于订单ID来查询订单。

 

  更进一步:

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

  大概只回去同个订单中的第一个条目。

  以后您应有清楚什么是分层结构了。它们并不是从严的平整,只是为了确定保证在你的劳务中这个强制的构造能够更便于被用户所知道。与持有软件开发中的技能一样,命名是大功告成的重庆大学。

  

  多看有个别API的示范并学会控制这么些技能,和你的队友一起来宏观你API财富的UCR-VIs。那里有部分APIs的事例:

财富命名的反例

  前边大家已经研讨过部分相宜的能源命名的例子,然则有时一些反面包车型地铁例证也很有教育意义。上面是局部不太具有RESTful风格的财富U君越Is,看起来比较混乱。那么些都以错误的例证! 

  首先,一些serivices往往利用单一的U中华VI来钦命服务接口,然后通过查询参数来钦点HTTP请求的动作。例如,要立异编号12345的用户消息,带有JSON
body的呼吁或许是这么:

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

  即便地点U汉兰达L中的”services”的这几个节点是2个名词,但以此URubiconL不是自解释的,因为对于具有的央求而言,该U帕杰罗I的层级结构都是千篇一律的。其它,它利用GET作为HTTP动词来施行二个翻新操作,那简直正是反人类(甚至是生命垂危的)。

  下边是其它3个翻新用户的操作的例子:

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

  以及它的七个变种:

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

  你会时不时看看在别的开发者的劳动套件中有许多那样的用法。可以见见,那个开发者试图去创建RESTful的财富名称,而且早已有了部分更上一层楼。可是你依旧能够分辨出U奥迪Q5L中的动词短语。注意,在这一个UCR-VL中我们不供给”update”那个词,因为大家能够借助HTTP动词来成功操作。下边这几个U奥迪Q7L正好表明了那点:

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

  那些请求同时存在PUT和”update”,那会对消费者产生迷惑!那里的”update”指的是三个财富吗?由此,那里我们费些口舌也是愿意您可见知道……

复数

  让我们来切磋一下复数和“单数”的争辩…还没据他们说过?但那种争议确实存在,事实上它能够总结为那个难点……

  在您的层级结构中U奥迪Q5I节点是还是不是供给被取名为单数或复数方式吗?举个例子,你用来寻觅用户能源的U君越I的命名是还是不是要求像上面这样:

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

  或者:

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

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

  遵照那个规则,八个行使复数方式的多节点的U汉兰达I会是这么(注意粗体部分):

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

  “customers”、“orders”以及“lineitems”这个U讴歌MDXI节点都应用的是复数方式。

  那意味你的各类根财富只必要两个中央的U奇骏L就足以了,1个用来成立集合内的财富,另二个用来依照标识符获取、更新和删除财富。例如,以customers为例,创建能源能够动用下边包车型客车UOdysseyL举办操作:

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

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

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

  正如前方提到的,给定的能源恐怕有多少个UWranglerI,但作为2个微细的全部的增删改查效率,利用八个不难的U本田CR-VI来拍卖就够了。

  或然你会问:是还是不是在稍微情形下复数没有意思?嗯,事实上是这么的。当没有集合概念的时候(此时复数没有意思)。换句话说,当财富只有二个的景况下,使用单数财富名称也是能够的——即二个纯净的能源。例如,假若有3个十足的全部布局能源,你能够采纳一个单数名称来代表:

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

  注意那里缺乏configuration的ID以及HTTP动词POST的用法。假诺各种用户有二个布署来说,那么这些U奥迪Q3L会是如此:

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

  同样令人瞩目那里没有点名configuration的ID,以及没有给定POST动词的用法。在那五个例证中,恐怕也会有人认为利用POST是卓有作用的。好吧…

 

归来表征

  正如前方提到的,RESTful接口协助各样财富特色,包涵JSON和XML,以及被包裹的JSON和XML。提议JSON作为暗许表征,不过服务端应该允许客户端钦定其余表征。

  对于客户端请求的表征格式,大家得以在Accept头通过文件扩张名来进展点名,也能够透过query-string等别的措施来钦命。理想图景下,服务端能够帮衬具备那几个点子。不过,以后专业更倾向于经过类似于文件扩大名的形式来实行点名。由此,建议服务端至少供给援救选用文件扩大名的方法,例如“.json”,“.xml”以及它们的包裹版本“.wjon”,“.wxml”。

  通过那种措施,在U哈弗I中内定重返表征的格式,能够增加U奥迪Q3L的可知性。例如,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格式的能源,将重临1个HTTP
404的荒唐。

  使用HTTP
Accept头被周边认为是一种更优雅的艺术,并且符合HTTP的正规化和含义,客户端能够透过那种形式来告诉HTTP服务端它们可支撑的数据类型有如何。但是,为了利用Accept头,服务端要同时援助封装和未封装的响应,你不能够不兑现自定义的连串——因为这么些格式不是正经的品类。那大大增添了客户端和服务端的复杂。请参见WranglerFC
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是什么”一节中也提到过。

  根据RoyFielding在他的博客中的描述(http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertextdriven),REST接口中最重点的片段是超文本的施用。其余,他还建议,在交付任何相关的音讯此前,2个API应该是可用和可掌握的。也正是说,二个API应当能够通过其链接导航到数码的次第部分。不提出只回去纯数据。

  可是当下的产业界先驱们并从未日常利用那种做法,那反映了HATEOAS仅仅在成熟度模型中的使用率更高。纵观者多的服务类别,它们基本上再次回到更多的数量,而回到的链接却很少(或然没有)。那是违反Fielding的REST约定的。Fielding说:“新闻的每一个可寻址单元都教导一个地方……查询结果应该展现为三个含有摘要音讯的链接清单,而不是目的数组。”

  另一方面,不难残暴地将全部链接集合重回会大大影响互联网带宽。在实质上情状中,依照所需的规则或行使情状,API接口的通讯量要基于服务器响应中中国足球球组织一流联赛文本链接所富含的“摘要”数量来平衡。

  同时,丰盛利用HATEOAS大概会追加完结的复杂性,并对劳务客户端发生显著的担当,这一定于降低了客户端和服务器端开发职员的生产力。因而,当务之急是要平衡超链接服务实践和水土保持可用财富之间的题材。

  超链接最小化的做法是在最大限度地收缩客户端和服务器之间的耦合的同时,提升服务端的可用性、可操纵性和可领会性。那么些最小化建议是:通过POST创制能源并从GET请求重临集合,对于有分页的场眼上边大家会波及。

微小化链接推荐

  在create的用例中,新建能源的U奇骏I(链接)应该在Location响应头中回到,且响应中央是空的——也许只包罗新建能源的ID。

  对于从服务端重返的本性集合,每种表征应该在它的链接集合中带走二个微细的“本身”链接属性。为了方便分页操作,其余的链接能够置身贰个独立的链接集合中回到,要求时得以分包“第贰页”、“上一页”、“下一页”、“最终一页”等音信。

  参照下文链接格式部分的例子获取更多音讯。

链接格式

  参照整个链接格式的专业,提出坚守一些类似Atom、AtomPub或Xlink的风骨。JSON-LD也不利,但并从未被周边采纳(假如已经被用过)。近期行业内部最广大的方法是使用含有”rel”成分和含有能源全部USportageI的”href”成分的Atom链接格式,不分包别的身份验证或询问字符串参数。”rel”成分得以涵盖标准值”alternate”、”related”、”self”、”enclosure”和”via”,还有分页链接的“第③页”、“上一页”、“下一页”,“最终一页”。在要求时可以自定义并加上应用它们。

  一些XML
Atom格式的定义对于用JSON格式表示的链接来说是无效的。例如,METHOD属性对于四个RESTful能源来说是不必要的,因为对此3个加以的财富,在颇具扶助的HTTP方法(CRUD行为)中,财富的ULANDI都以同样的——所以单独列出这几个是尚未供给的。

  让我们举一些实际的例子来一发证实那或多或少。下边是调用创立新能源的央求后的响应:

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

  下边是响应头集合中涵盖创立新能源的U纳瓦拉I的Location部分:

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

  重临的body能够为空,只怕隐含1个棉被服装进的响应(见下文封装响应)。

  下边包车型大巴例子通过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集合中的每一项都包罗1个针对性“本人(self)”的链接。那里只怕还会有部分提到到集结的此外链接,但都与分页本身非亲非故。简单的说,那里有七个地点含有links。二个就是data对象中所包涵的成团(那几个也是接口要回到给客户端的数码表征集合),当中的每一项至少要包含二个针对性“自个儿(self)”的links集合;另三个则是1个单独的指标links,其中囊括和分页相关的链接,该片段的始末适用于漫天集合。

  对于经过POST请求创立能源的景色,供给在响应头中包罗三个事关新建对象链接的Location

打包响应

   服务器能够在响应中并且再次来到HTTP状态码和body。有为数不少JavaScript框架没有把HTTP状态响应码再次来到给最终的开发者,那频仍会导致客户端不可能依照情状码来鲜明具体的表现。别的,纵然HTTP规范中有很各个响应码,但是往往只有个别客户端会关切这几个——日常大家只在乎”success”、”error”或”failture”。因而,将响应内容和响应状态码封装在含蓄响应新闻的特性中,是有必不可少的。

  OmniTI
实验室有诸如此类二个提议,它被喻为JSEND响应。更加多新闻请参考http://labs.omniti.com/labs/jsend。此外二个提案是由DouglasCrockford提议的,能够查看那里http://www.json.org/JSONRequest.html

  那些提案在实践中并不曾完全涵盖全部的情事。基本上,以往最好的做法是依照以下属性封装常规(非JSONP)响应:

  • code——包蕴一个整数品类的HTTP响应状态码。
  • status——包罗文本:”success”,”fail”或”error”。HTTP状态响应码在500-599时期为”fail”,在400-499时期为”error”,别的均为”success”(例如:响应状态码为1XX、2XX和3XX)。
  • message——当状态值为”fail”和”error”时有效,用于突显错误音讯。参照国际化(il8n)标准,它能够包含新闻号或许编码,能够只含有个中八个,大概同时富含并用分隔符隔离。
  • data——包涵响应的body。当状态值为”fail”或”error”时,data仅包蕴错误原因或越发名称。

  上边是贰个重临success的包装响应:

{
  "code": 200,
  "status": "success",
  "data": {
    "lacksTOS": false,
    "invalidCredentials": false,
    "authToken": "4ee683baa2a3332c3c86026d"
  }
}

  重返error的包裹响应:

{
  "code": 401,
  "status": "error",
  "message": "token is invalid",
  "data": "UnauthorizedException"
}

  这多少个包裹响应对应的XML如下:

<response>
    <code>200</code>
    <status>success</status>
    <data class="AuthenticationResult">
        <lacksTOS>false</lacksTOS>
        <invalidCredentials>false</invalidCredentials>
        <authToken>1.0|idm|idm|4ee683baa2a3332c3c86026d</authToken>
    </data>
</response>

  和:

<response>
    <code>401</code>
    <status>error</status>
    <message>token is invalid</message>
    <data class="string">UnauthorizedException</data>
</response>

拍卖跨域难题

   我们都闻讯过有关浏览器的同源策略或同源性须求。它指的是浏览器只好请求当前正值显示的站点的财富。例如,假使当前正在展现的站点是www.Example1.com,则该站点不可能对www.Example.com倡导呼吁。显明那会潜移默化站点访问服务器的法子。

  最近有四个被大面积接受的支撑跨域请求的不二法门:JSONP和跨域能源共享(CO奥迪Q5S)。JSONP或“填充的JSON”是一种选用方式,它提供了2个主意请求来自分化域中的服务器的多寡。其行事方法是从服务器重回任意的JavaScript代码,而不是JSON。客户端的响应由JavaScript解析器实行辨析,而不是一向解析JSON数据。此外,CO大切诺基S是一种web浏览器的技巧标准,它为web服务器定义了一种格局,从而允许服务器的财富能够被分歧域的网页访问。COCR-VS被看做是JSONP的新颖替代品,并且能够被有着现代浏览器帮忙。由此,不提议选拔JSONP。任何动静下,推荐选拔COEscortS。

支持CORS

  在服务端完结COKugaS很粗大略,只要求在出殡和埋葬响应时顺便HTTP头,例如: 

Access-Control-Allow-Origin: *

  唯有在多少是国有使用的景色下才会将访问来源设置为”*”。超越二分一意况下,Access-Control-Allow-Origin头应该钦点哪些域能够倡导一个CO卡宴S请求。只有须求跨域访问的UPRADOL才设置CO宝马X5S头。

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

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

Access-Control-Allow-Credentials: true

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

  那个headers能够透过web服务器、代理来展开安插,或然从服务器本身发送。不引进在服务端完毕,因为很不灵活。只怕,能够行使方面包车型大巴第二种艺术,在web服务器上配备三个用空格分隔的域的列表。更加多关于CO中华VS的始末能够参见那里:http://enable-cors.org/

支持JSONP

  JSONP通过利用GET请求避开浏览器的限制,从而完结对富有服务的调用。其行事原理是请求方在伏乞的U君越L上添加一个字符串查询参数(例如:jsonp=”jsonp_callback”),当中“jsonp”参数的值是JavaScript函数名,该函数在有响应重返时将会被调用。

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

  JSONP经常在有的不帮助COXC60S的老旧浏览器中运用,倘若要改成援助CO景逸SUVS的,会潜移默化总体服务器的架构。只怕大家也得以因此代理来落到实处JSONP。由此可见,JSONP正在被CO奇骏S所代表,大家应该尽量地利用CO凯雷德S。

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

  1. 响应体必须封装成3个参数字传送递给jsonp中钦赐的JavaScript函数(例如:jsonp_callback(“<JSON
    response body>”))。
  2. 一向重回HTTP状态码200(OK),并且将忠实的景况作为JSON响应中的一局地重返。

  别的,响应体中平常必须带有响应头。那使得JSONP回调方法供给依照响应体来规定响应处理格局,因为它自个儿不能得知真实的响应头和状态值。

  下边包车型客车事例是根据上述方法封装的1个回去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'}")

 

询问,过滤和分页

  对于大数据集,从带宽的角度来看,限制重返的数据量是那1个重要的。而从UI处理的角度来看,限制数据量也同样主要,因为UI通常只好展现大数目汇总的一小部分多少。在数据集的增长速度不分明的气象下,限制暗中认可再次回到的数据量是很有必不可少的。以Instagram为例,要获取有些用户的推文(通过个人主页的年华轴),假若没有特别钦命,请求私下认可只会回来20条记下,即便系统最多能够回到200条记下。

  除了限制再次来到的数据量,大家还索要考虑怎么着对天意据集实行“分页”或下拉滚动操作。创设数量的“页码”,再次回到大数额列表的已知片段,然后标出数据的“前一页”和“后一页”——这一作为被称之为分页。此外,大家兴许也亟需内定响应少将包蕴怎样字段或性质,从而限制重临值的数额,并且大家愿意末了能够因此特定值来举行询问操作,并对重回值实行排序。

  有三种首要的方法来还要限定查询结果和执行分页操作。首先,大家得以创制多个索引方案,它能够以页码为导向(请求中要提交每一页的记录数及页码),也许以记录为导向(请求中直接提交第叁条记下和尾声一条记下)来规定重返值的胚胎地方。举个例子,那二种方法分别代表:“给出第陆页(如果每页有20条记下)的笔录”,或“给出第70到第③20条的记录”。

  服务端将依据运作体制来展开切分。有个别UI工具,比如Dojo
JSON会选取模仿HTTP规范使用字节范围。如果服务端援助out of
box(即开箱即用效应),则前端UI工具和后端服务时期无需任何转换,那样使用起来会很便利。

  下文将介绍一种艺术,既能够支持Dojo这样的分页情势(在请求头中提交记录的界定),也能支撑采用字符串查询参数。那样一来服务端将变得愈加灵敏,既能够运用类似Dojo一样先进的UI工具集,也能够动用简易直接的链接和标签,而无需再为此扩大复杂的支付工作。但借使服务不直接援助UI效能,能够考虑不要在请求头中提交记录范围。

  要特别提议的是,我们并不引进在全体服务中应用查询、过滤和分页操作。并不是兼备能源都默许帮助那个操作,唯有少数特定的财富才支撑。服务和能源的文书档案应当表达什么接口援助那个扑朔迷离的机能。

结果限制

  “给出第③到第伍5条的记录”,那种请求数据的点子和HTTP的字节范围规范更平等,由此大家得以用它来标识Range
header。而“从第①条记下初步,给出最多20条记下”那种艺术更易于阅读和精通,因而大家常见会用字符串查询参数的法门来代表。

  综上所述,推荐既援救使用HTTP Range
header,也辅助使用字符串查询参数——offset(偏移量)和limit(限制),然后在服务端对响应结果举办界定。注意,假诺还要扶助那二种艺术,那么字符串查询参数的预先级要超越Range
header。

  那里你或许会有个问号:“那三种格局效果相似,不过回去的多寡不完全一致。那会不会令人歪曲呢?”恩…那是四个难点。首先要回应的是,那实在会令人歪曲。关键是,字符串查询参数看起来尤其清晰易懂,在营造和剖析时更是有益于。而Range
header则更加多是由机械来利用(偏向于底层),它更是适合HTTP使用标准。

  综上可得,解析Range
header的工作会扩大复杂度,相应的客户端在构建请求时也急需展开部分拍卖。而选取单独的limit和offset参数会愈发不难明白和创设,并且不供给对开发职员有更加多的要求。

用范围标记举办限定

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

  Range: items=0-24

  注意记录是从0初始的一而再字段,HTTP规范中申明了什么使用Range
header来请求字节。也便是说,假诺要央求数据集中的第贰条记下,范围应该从0早先算起。上述的乞请将会回到前2四个记录,尽管数据汇总至少有25条记下。

  而在服务端,通过检查请求的Range
header来鲜明该再次回到哪些记录。只要Range
header存在,就会有八个简练的正则表明式(如”items=(\d+)-(\d+)”)对其进展辨析,来获得要寻找的范围值。

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

  字符串查询参数被视作Range
header的替代选择,它选择offset和limit作为参数名,个中offset代表要询问的率先条记下编号(与上述的用来范围标记的items第二个数字同样),limit代表记录的最大条数。下面包车型大巴事例再次回到的结果与上述用范围标记的例证一样:

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

  Offset参数的值与Range
header中的类似,也是从0先导总括。Limit参数的值是回到记录的最大数量。当字符串查询参数中未钦赐limit时,服务端应当提交叁个缺省的最大limit值,可是那一个参数的施用都需求在文书档案中开始展览表明。

据说范围的响应

  对二个基于范围的呼吁来说,无论是通过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条记下,要来得第3页数据,Range
header的始末如下:

  Range: items=25-49

  同样,用字符串查询参数表示如下:

  GET …?offset=25&limit=25

  服务端会相应地回去一组数据,附带的Content-Range header内容如下:

  Content-Range: 25-49/66

  在半数以上情状下,那种分页方式都未曾难题。但有时会有那种情状,正是要赶回的记录数据不或然直接表示成多少集中的行号。还有正是有些数据集的变型非常快,不断会有新的多少插入到数量集中,这样自然会招致分页出现难点,一些再一次的数目大概会现出在不一样的页中。

  按日期排列的数据集(例如推文(Tweet)feed)正是一种常见的图景。固然你还是得以对数据开始展览分页,但神跡用”after”或”before”那样的首要性字并与Range
header(恐怕与字符串查询参数offset和limit)合营来兑现分页,看起来会越加简明易懂。

  例如,要博取给定时间戳的前20条评论:

  GET
http://www.example.com/remarks/home\_timeline?after=&lt;timestamp&gt

  Range: items=0-19

  GET
http://www.example.com/remarks/home\_timeline?before=&lt;timestamp&gt

*  Range: items=0-19*

  用字符串查询参数表示为:

  GET
http://www.example.com/remarks/home\_timeline?after=&lt;timestamp&gt;&offset=0&limit=20 

*  GET
http://www.example.com/remarks/home\_timeline?before=&lt;timestamp&gt;&offset=0&limit=20*

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

  假设请求时并未点名要回去的数码范围,服务端再次回到了一组默许数据或限制的最大数据集,那么服务端同时也应当在回来结果中含有Content-Range
header来和客户端实行确认。以地点个人主页的时光轴为例,无论客户端是否内定了Range
header,服务端每一次都只回去20条记下。此时,服务端响应的Content-Range
header应该包括如下内容:

  Content-Range: 0-19/4125

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

结果的过滤和排序

  针对重返结果,还索要考虑怎么在服务端对数码进行过滤和排列,以及怎么着按钦命的依次对子数据开展搜寻。那几个操作能够与分页、结果限制,以及字符串查询参数filter和sort等相结合,能够兑现强大的数据检索功用。

  再强调2遍,过滤和排序都以错综复杂的操作,不需求暗许提需求全体的能源。下文将介绍如何能源供给提供过滤和排序。

过滤

  在本文中,过滤被定义为“通过一定的基准来规定必供给赶回的多寡,从而减弱重返的数据”。假诺服务端援救一套完整的相比较运算符和复杂的原则13分,过滤操作将变得一定复杂。可是大家数见不鲜会使用部分简约的表明式,如starts-with(以…初阶)或contains(包含)来展开匹配,以担保再次回到数据的完整性。

  在大家开始钻探过滤的字符串查询参数在此以前,必须先清楚为啥要采纳单个参数而不是多少个字符串查询参数。从根本上来说是为了削减参数名称的争辨。我们早就有offsetlimitsort(见下文)参数了。假使或许的话还会有jsonpformat标识符,恐怕还会有afterbefore参数,那个都以在本文中关系过的字符串查询参数。字符串查询中选择的参数愈来愈多,就越只怕导致参数名称的争论,而选取单个过滤参数则会将争辩的恐怕降到最低。

  其它,从服务端也很简单仅经过单个的filter参数来判断请求方是不是要求多少过滤效果。假若查询须求的复杂度扩充,单个参数将更具备灵活性——能够协调树立一套效能一体化的查询语法(详见下文OData注释或访问http://www.odata.org)。

  通过引入一组广泛的、公认的分隔符,用于过滤的表明式能够以老大直观的花样被选取。用那一个分隔符来设置过滤查询参数的值,那些分隔符所创造的参数名/值对可以越来越不难地棉被和衣服务端解析并增强数据查询的属性。近期已有些分隔符包含用来分隔各个过滤短语的竖线(”|”)和用来分隔参数名和值的双冒号(”::”)。那套分隔符丰硕唯一,并符合大部分情景,同时用它来营造的字符串查询参数也进一步简单了然。上边将用1个大致的例子来介绍它的用法。若是我们想要给名为“托德”的用户们发送请求,他们住在西雅图,有着“Grand
Poobah”之称。用字符串查询参数完成的伏乞UPAJEROI如下:

  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举行版本化管理是幸免那种重庆大学变更的一种有效方法。

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

  未来,版本管理通过UKugaI自己的本子号来形成,客户端在乞请的USportageI中标明要获得的财富的版本号。事实上,许多大商户如推特(TWTR.US)、Yammer、推特(TWTR.US)、谷歌等不时在他们的U昂科雷I里使用版本号。甚至像WSO2那样的API管理工科具也会在它的U昂CoraLs中供给版本号。

  面向REST原则,版本管理技术快捷发展。因为它不含有HTTP规范中放到的header,也不帮衬仅当2个新的财富或概念被引入时才应该添加新UOdysseyI的意见——即版本不是表现方式的变化。另二个反对的理由是财富U安德拉I是不会随时间改变的,财富正是财富。

  U揽胜极光I应该能不难地辨认能源——而不是它的“形状”(状态)。另2个便是必须钦点响应的格式(表征)。还有一部分HTTP
headers:Accept 和 Content-Type。Accept
header允许客户端钦定所期待或能支撑的响应的传播媒介类型(一种或各样)。Content-Type
header可分别被客户端和劳动端用来钦命请求或响应的数目格式。

  例如,要拿走3个user的JSON格式的数目:

  #Request:

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

  #Response:

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

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

  以往,大家对相同能源请求版本2的数据:

  #Request:

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

  #Response:

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

  {“id”:”12345″, “firstName”:”Joe”, “lastName”:”DiMaggio”}

  Accept
header被用来代表所希望的响应格式(以及示例中的版本号),注意上述多个一样的U牧马人I是哪些做到在差异的本子中分辨财富的。恐怕,假设客户端须要3个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应当重临3个不当的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的改动会带来什么样的结果,保障起见最好考虑选取版本控制。当您在设想提供3个新本子是不是确切时,恐怕考虑对现有的回来表征进行改动是不是肯定能满意急需并被客户端所收受时,有如此多少个成分要考虑。

破坏性的改动

  • 变动属性名(例如将”name”改成”firstName”)
  • 去除属性
  • 变更属性的数据类型(例如将numeric变为string,
    boolean变为bit/numeric,string 变为 datetime等等)
  • 变动验证规则
  • 在Atom样式的链接中,修改”rel”的值
  • 在现有的工作流中引入供给财富
  • 改变能源的概念/意图;概念/意图或能源意况的意思不一致于它原有的意思。例如:
    • 贰个content
      type是text/html的能源,此前表示的是装有援救的媒体类型的2个”links”集合,而新的text/html则意味着的是用户输入的“web浏览器表单”。
    • 一个包罗”endTime”参数的API,对财富”…/users/{id}/exams/{id}”表明的意义是学生在尤其时刻付诸试卷,而新的含义则是考查的约定完结时间。
  • 经过抬高新技术的字段来改变现有的财富。将七个能源统一为3个并弃用原始的财富。
    • 有诸如此类三个能源”…/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来提升响应

  可选。见奥迪Q7DF(Resource Description Framework,即能源描述框架)规范。

带有Content-Type的链接

  Atom风格的链接支持”type”属性。提供丰裕的音讯以便客户端能够对特定的本子和剧情类型进行调用。

找出扶助的版本

自身应当同时扶助多少个版本?

  维护多少个差异的本子会让劳作变得繁琐、复杂、简单出错,而且代价高,对于别的给定的能源,你应有帮助不抢先3个版本。

弃用

  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中是以字符串的格式存在的,假使未钦赐统一的格式,那么解析日期也会是2个标题。

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

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

  有一个大约的点子能够缓解那些题材——在字符串中始终用同一的格式,包涵时间片(带有时区音讯)。ISO8601时间格式是3个科学的消除方案,它采纳了一心增强的岁月格式,包涵小时、分钟、秒以及秒的小数部分(例如yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)。建议在REST服务的body内容中(请求和响应均包罗)使用ISO8601代表享有的日子格式。

  顺便提一下,对于那么些基于JAVA的劳务来说,Date艾达pterJ库使用DateAdapter,Iso8601TimepointAdapter和HttpHeaderTimestampAdapter类能够卓殊不难地分析和格式化ISO860113日期和岁月,以及HTTP
1.1
header(昂CoraFC1123)格式。可以从https://github.com/tfredrich/DateAdapterJ下载。

  对于这么些成立基于浏览器的用户界面来说,ECMAScript5规范一开首就包涵了JavaScript解析和创设ISO8607日期的剧情,所以它应当改成大家所说的主流浏览器所服从的法门。当然,倘诺您要帮助那多少个不可能自动解析日期的旧版浏览器,能够应用JavaStript库或正则表明式。那里有多少个能够分析和创建ISO8601时间的JavaStript库:

  http://momentjs.com/

  http://www.datejs.com/

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

  但是上述建议仅适用于HTTP请求或响应内容中的JSON和XML内容,HTTP规范针对HTTP
headers使用另一种差异的格式。在被RAV4FC1123更替的RFC82第22中学建议,该格式包含了各个日期、时间和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. 万一授权通过了,服务器将会持续健康运转。

  上边第2步的支付或者会比较大,可是一旦假设存在1个可缓存的权位控制列表(ACL),那么在发生远程请求前,能够在当地成立三个授权客户端来缓存最新的ACLs。

身份验证

  近日最好的做法是应用OAuth身份验证。强烈推荐OAuth2,不过它仍然居于草案景况。或然接纳OAuth1,它完全能够胜任。在少数景况下也得以接纳3-Legged
OAuth。越来越多关于OAuth的标准可以查阅那里http://oauth.net/documentation/spec/

  OpenID是1个附加选取。可是提出将OpenID作为一个叠加的身份验证选项,以OAuth为主。更加多关于OpenID的规范能够查看那里http://openid.net/developers/specs/

传输安全

  全数的求证都应有运用SSL。OAuth2供给授权服务器和access
token(访问令牌)来使用TLS(安全传输层协议)。

  在HTTP和HTTPS之间切换会带来安全隐患,最好的做法是兼具简报私下认可都使用TLS。

授权

  对劳务的授权和对别的应用程序的授权一样,没有其余不同。它依据那样二个难题:“主体是或不是对给定的资源有请求的许可?”那里给出了简便的三项数据(主体,能源和批准),因而很简单构造多少个支撑那种概念的授权服务。个中核心是被予以财富访问许可的人或系统。使用那个相似概念,就能够为每二个大旨营造三个缓存访问控制列表(ALC)。

应用程序安全

  对RESTful服务来说,开发2个安然无恙的web应用适用同样的口径。

  • 在服务器上印证全部输入。接受“已知”的不错的输入并驳回错误的输入。
  • 防止SQL和NoSQL注入。
  • 行使library如微软的Anti-XSS或OWASP的AntiSammy来对输出的数目开始展览编码。
  • 将音讯的长短限制在规定的字段长度内。
  • 劳动应该只展现一般的错误新闻。
  • 考虑工作逻辑攻击。例如,攻击者能够跳过多步骤的预购流程来预定产品而无需输入信用卡音讯呢?
  • 对困惑的位移记录日志。

  RESTful安全要求留意的位置:

  • 表明数据的JSON和XML格式。
  • HTTP动词应该被限制在允许的主意中。例如,GET请求不能去除1个实体。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值,该时间戳(奥迪Q5FC1123格式)表示的是响应过期的小时,也正是Date(例如当前些天子)加上最大age值。假诺响应不扶助缓存,该headers不存在。

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

Pragma

当Cache-Control为no-cache时,该header的值也被安装为no-cahche。不然,不存在。

Pragma: no-cache

Last-Modified

财富本人最终被涂改的时光戳(瑞虎FC1123格式)。

Last-Modified: Sun, 06 Nov1994 08:49:37 GMT

  为了简化,那里举二个响应中的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)
—— 无论能源存不设有,无论是或不是有40① 、403的范围,当呼吁的能源找不到时,出于安全因素考虑,服务器都得以运用该错误码来掩饰。

  409 (CONFLICT)
—— 每当执行请求恐怕会滋生产资料源争辨时使用。例如,存在双重的实体,当不帮忙级联删除时去除根对象。

  500 (INTERNAL SERVER ERROR)
—— 当服务器抛出很是时,捕捉到的貌似错误。

 

叠加财富

书籍

  REST API Design Rulebook,Mark Masse, 2011, O’Reilly Media, Inc.

  RESTful Web Services, Leonard Richardson and Sam Ruby, 2008,
O’Reilly Media, Inc.

*  RESTful Web Services Cookbook, Subbu Allamaraju, 2010, O’Reilly
Media, Inc.*

  REST in Practice: Hypermedia and Systems Architecture, Jim Webber,
et al., 2010, O’Reilly Media, Inc.

  APIs: A Strategy Guide, Daniel Jacobson; Greg Brail; Dan Woods,
2011, O’Reilly Media, Inc.

网站

  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