RESTful服务最佳实践

小说:明珠的风险作者:安伯更新时间:2019-03-27字数:88816

最终还是没有推开营帐,唐欣脚踏腾龙戏珠步,瞬间的朝着军营旁的草地上奔去,因为他看到了一个人的影子在那里,那个影子,他很熟悉。

明珠的风险

“他想做什么?真是奇怪的斗技好像将自身的气息完全封锁不泄露出去,如果我不是这个空间的主人,他不是身处这个空间的话都察觉不到他在哪里。”在不知名的地方刘皓的表现都落在了中年人眼中,他没有对刘皓隐瞒,这个考验真的只是靠运气,如果有这个运气一脚踏出就是出口的那么还真的能得到传承。
那些人在听到叶扬这么说后,顿时抬起了头,再次看向他,想要听听他还要说什么。

“艾斯德斯,小心,她是琼华派掌门太清,曾经压制得蜀山派抬不起头来,斩杀蜀山派掌门的太清道人。”柳梦璃传音道。

RESTful服务最佳实践


本文主要读者

引言

REST是什么

  统一接口

    基于资源

    通过表征来操作资源

    自描述的信息

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

  无状态

  可缓存

  C-S架构

  分层系统

  按需编码(可选)

REST快速提示

  使用HTTP动词表示一些含义

  合理的资源名

  XML和JSON

  创建适当粒度的资源

  考虑连通性

定义

  幂等性

  安全

HTTP动词

  GET

  PUT

  POST

  PUT和POST的创建比较

  DELETE

资源命名

  资源URI示例

  资源命名的反例

  复数

返回表征

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

    最小化链接推荐

    链接格式

  封装响应

  处理跨域问题

    支持CORS

    支持JSONP

查询,过滤和分页

  结果限制

    用范围标记进行限制

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

    基于范围的响应

  分页

  结果的过滤和排序

    过滤

    排序

服务版本管理

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

  当没有指定版本时,返回什么版本?

  请求不支持的版本

  什么时候应该创建一个新版本?

    破坏性的修改

    非破坏性的修改

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

  利用Content-Location来增强响应

  带有Content-Type的链接

  找出支持的版本

    我应该同时支持多少个版本?

    弃用

    我如何告知客户端被弃用的资源?

日期/时间处理

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

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

保护服务的安全

  身份验证

  传输安全

  授权

  应用程序安全

缓存和可伸缩性

  ETag Header

HTTP状态码(前10)

附加资源

  书籍

  网站

 

本文主要读者

  该最佳实践文档适用于对RESTful Web服务感兴趣的开发人员,该服务为跨多个服务的组件提供了较高的可靠性和一致性。按照本文的指导,可快速、广泛、公开地为内外部客户采用。

  本文中的指导原则同样适用于工程师们,他们希望使用这些依据最佳实践原则开发的服务。虽然他们更加关注缓存、代理规则、监听及安全等相关方面,但是该文档能作为一份涵盖所有种类服务的总指南。

  另外,通过从这些指导原则,管理人员了解到创建公共的、提供高稳定性的服务所需花费的努力,他们也可从中受益。

 

引言

  现今已有大量关于RESTful Web服务最佳实践的相关资料(详见本文最后的相关文献部分)。由于创作的时间不同,许多资料中的内容是矛盾的。此外,想要通过查阅文献来了解这种服务的发展是不太可取的。为了了解RESTful这一概念,至少需要查阅三到五本相关文献,而本文将能够帮你加速这一过程——摒弃多余的讨论,最大化地提炼出REST的最佳实践和规范。

  与其说REST是一套标准,REST更像是一种原则的集合。除了六个重要的原则外就没有其他的标准了。实际上,虽然有所谓的“最佳实践”和标准,但这些东西都和宗教斗争一样,在不断地演化。

  本文围绕REST的普遍问题提出了意见和仿食谱式的讨论,并通过介绍一些简单的背景知识对创建真实情境下的预生产环境中一致的REST服务提供知识。本文收集了来自其他渠道的信息,经历过一次次的失败后不断改进。

  但对于REST模式是否一定比SOAP好用仍有较大争议(反之亦然),也许在某些情况下仍需要创建SOAP服务。本文在提及SOAP时并未花较大篇幅来讨论它的相对优点。相反由于技术和行业在不断进步,我们将继续坚持我们的假设–REST是当下设计web服务的最佳方法。

  第一部分概述REST的含义、设计准则和它的独特之处。第二部分列举了一些小贴士来记忆REST的服务理念。之后的部分则会更深入地为web服务创建人员提供一些细节的支持和讨论,来实现一个能够公开展示在生产环境中的高质量REST服务。

 

REST是什么?

  REST架构方式描述了六种设计准则。这些用于架构的设计准则,最早是由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<

当前文章:http://zxqss.com/content/2018-11/23/content_96251.html

发布时间:2019-03-27 06:33:54

三成网民“不快乐” 网瘾难逃离 人民币贬值对我们意味着什么? 不弃旧也迎新 戒除心毒,便可成就未来。 文创监理 - 黄胤然首倡文创理念 孩子的鲜血,能换回父母的觉醒吗? “情绪识别”就是“安全教育” 来生再也不爱你

有氧运动之父--肯尼斯·库珀 如何应该孩子的负面情绪 早死心 早解脱—从《琅琊榜》说开去 | 晓雅 【情感问答】考研和爱情哪个更重要? 别让李嘉诚跑了 触目惊心的当代“官赌” 向死而生:从《道士下山》到天津爆炸,来谈谈生死 与火机恋爱的女人 我们对校园凶杀案反思的重大失误导致凶杀案连续发生! 你是那个内心强大的人吗? 郭美美一审被判5年,上诉还会减刑吗? 面对灾难,让我们紧急行动起来,预防心理创伤! 震惊!教育有一个大家没有意识到的陷阱 十条经营婚姻的金科玉律 永远不要考验人性 青春期——改变人生的最后机会 双章书法内容详释 旅途中一见钟情,咋办? 成长营:优秀的孩子也需要成长

编辑:秉邓成戏

我要说两句: (0人参与)

发布