RESTful WebServices Cookbook中文版

RESTful WebServices Cookbook中文版

[美]Subbu Allamaraju（沙布·阿拉马拉尤）著

丁雪丰译

ISBN978-7-121-14390-8

2011年9月出版

定价：59.00元

16开

320页

内 容 简 介

本书是《RESTful Web Services Cookbook》的中文翻译版。

本书从实践出发，涉及设计RESTful Web服务的各个方面，通过问题描述、解决方案、问题讨论的形式在14个章节中详细讨论了统一接口、资源、表述、URI、链接、请求、缓存、安全等诸多内容。无论读者是否设计过RESTful Web服务，具体使用哪种语言，都能在阅读过程中有所收获。本书也可作为手册，根据具体问题描述在书中查找解决办法。

前 言

2000年，HTTP和URI的关键贡献者RoyFielding在题为“Architectural Styles and the Design of Network-BasedSoftware Architectures”注 的博士论文中精确地阐述了Web的架构。在这篇论文中，他引入了一种名为表述性状态转移注 （Representational State Transfer，REST）的架构风格。抽象地说，这种风格描述了WorldWide Web的基础，其组成技术包括Hypertext Transfer Protocol（HTTP）、UniformResource Identifier（URI）、类似HTML和XML的标记语言以及类似JSON这样的适用于Web的格式。

REST是一种面向网络化应用程序的架构风格，其中包含了很多用于描述分离关注点、可见性、可靠性、可扩展性、性能等诸多方面的约束。附录B是对这些约束的一个简单概述。Web的基础设施使得开发者倾向于用REST来构建分布式的、去中心化的客户端/服务器应用程序。在这些基础设施上部署Web服务让你可以利用众多已有的基础设施，其中包括Web服务器、客户端库、代理服务器、缓存、防火墙等。尽管从理论上来说，能够脱离HTTP来构建RESTful的应用程序，但这样做的代价很大。在本书中，RESTful Web服务指的是通过HTTP，URI，XML，JSON和Atom等技术构建的Web服务。

本书范围

本书并非针对REST的论文，也不是在描述它相对于其他架构风格的优点，而是为RESTful Web服务的设计者和开发者提供的一本指南。

目前已经有大量描述REST架构风格的材料了。Wikipedia关于表述性状态转移的条目（http://en.wikipedia.org/wiki/Representational_State_Transfer）中提供了REST基础概念的精确描述、约束、设计应用程序的指导原则。Leonard Richardson和Sam Ruby的“RESTful Web Services”（O’Reilly）注 更深入地探讨了这个主题，详细讲述了如何将资源用做核心构建部件。但在日常的设计与实现中遇到了问题该如何获取帮助呢？本书就是来弥补这个空缺的。

本书由多个用于帮助设计及实现RESTful客户端/服务器应用程序的技巧组成，无论你的Web服务是否是RESTful的，它们都能帮你利用好Web基础设施和REST。每个小节都包含一个或多个问题描述和一个解决方案，随后的详细讨论中有例子、关于实现的讨论和所涉及的各种权衡考虑。

书中的多数材料都基于开发RESTful Web服务时遇到的常见设计问题，包括HTTP使用、资源和表述设计、URI、缓存、并发控制、部分更新（partialupdates）、批处理、事务、安全、版本控制、兼容性等内容。

本书并不特定于某种编程语言，其中使用HTTP请求和响应消息来说明实现。你可以用C#，C++，Java，Ruby，Python，PHP和Perl这样的语言来进行实现。附录A里有一个针对特定语言的图书列表，你也可以去你喜欢的书店找找。

本书也不涉及安装、管理或保护Web服务器、缓存及代理。可以参考KenCoar和Rich Bowen的“ApacheCookbook”注 、Ivan Ristic的“Apache Security”和Duane Wessels的“Squid: The Definitive Guide”注 （全由O’Reilly出版），或者产品手册来了解相关主题。

辅助材料

访问http://www.restful-webservices-cookbook.org可获得关于本书的附加材料、勘误、评论与问题。

下面这些资源十分有用：

REST-Discuss Yahoo! Group（http://tech.groups.yahoo.com/group/rest-discuss）

如果你有REST架构风格相关的问题，可以检索该讨论组的存档。更好的做法是加入讨论组，发表你的问题，参与有关REST优缺点、常见问题和针对RESTfulWeb服务的HTTP用法的讨论。

Leonard Richardson和Sam Ruby的“RESTful Web Services”（O’Reilly）

阅读此书可更多地了解REST以及如何使用Web作为构建RESTful Web服务的平台。

RESTwiki（http://rest.blueoxen.net/cgi-bin/wiki.pl）

该Wiki中收录了多年来编写的描述REST多个方面及其应用程序的文章。

Chris Shiflett的“HTTPDeveloper’s Handbook”（Sams）

如果你在客户端或服务器端应用程序中使用HTTP时遇到问题，可以阅读此书。

毫无疑问，会有本书以及之前讨论到的资源中没有涵盖到的设计与实现问题，请访问http://www.restful-webservices-cookbook.org发表你的问题、建议或者是你成功实施过的其他解决方案。在适当的时候，该站点将包含更多技巧，并且它们将被收入本书的下一个修订版中。

本书内容

如下所示，本书分为14个章节和5个附录：

第1章，使用统一接口

本章描述了使用HTTP统一接口以及处理诸如无状态、可见性、安全性和幂等性、可扩展性、创建新资源、GET还是POST等问题的细节。本章的内容主要关注于使用HTTP的统一接口。

第2章，识别资源

本章描述了如何识别资源以涵盖常见应用场合。

第3章，设计表述

本章描述了如何设计表述，如何使用请求和响应的HTTP标头，如何选择媒体类型和格式，以及如何进行错误处理。

第4章，设计URI

本章描述了设计URI、将URI作为标识符和保持良好URI的常见方法。

第5章，Web链接

本章展示了何时应该在表述中使用链接，如何使用，还涉及表述正文中链接的详细情况、链接头、URI模板和链接的应用。

第6章，Atom和AtomPub

本章介绍了如何使用Atom Feed、Entry、媒体资源以及将文档作为资源；如何使用AtomPub协议；何时使用Atom来设计资源表述。

第7章，内容协商

本章展示了如何基于媒体类型、字符编码、内容编码或内容语言来协商表述；如何使用Vary头；何时使用内容协商。

第8章，查询

本章展示了一些针对查询设计URI、处理大查询和存储查询的方法。

第9章，Web缓存

本章描述了如何在服务器上支持过期缓存以及如何在客户端处理缓存。

第10章，条件请求（ConditionalRequests）

本章描述了如何在服务器与客户端针对多种HTTP方法实现条件请求，并展示了条件请求是如何帮助进行缓存、乐观并发控制和保证幂等性的。

第11章，其他内容

本章展示了如何解决那些初看超出REST和HTTP范畴的设计问题。其中的主题包括复制、合并、部分更新、批处理和事务。

第12章，安全

本章展示了如何满足常见安全需求，例如身份验证（authentication）、授权（authorization）、代理（delegation）等。

第13章，可扩展性与版本控制

本章展示了如何编写可扩展的服务器，如何让客户端对变化保持弹性，如何实现版本控制。

第14章，服务发现（Discovery）

本章描述了如何为RESTful Web服务编写文档。

附录A，辅助读物

这个附录中提供了一些资源，你能从中找到更多关于REST及其基础技术的信息。

附录B，REST概述

这个附录中提供了一个REST的简要介绍，并带有一个示例。

附录C，HTTP方法

这个附录中展示了如何使用标准HTTP方法。

附录D，AtomSyndication Format

这个附录中提供了一个关于Atom Feed和Entry文档的参考。

附录E，链接关系类型

这个附录中罗列了读者能在链接中使用的链接关系类型（link relation type）。

本书使用的约定

本书中使用如下排版约定：

斜体

表示新术语、URL、电子邮件地址、文件名及文件扩展名。

定宽字体

用于程序示例、在段落中引用程序元素，例如变量或函数名、数据库、数据类型、环境变量、语句及关键字。

“#”开头的定宽字体

用于表示HTTP请求和响应消息中的注释。例如：

# 这是一个请求

GET /toc

Host: www.restful-webservices-cookbook.org

# 这是一个响应

HTTP/1.1 200 OK

Date: Sat, 07 Nov 2009 03:14:05 GMT

Last-Modified: Sat, 07 Nov 2009 03:14:05 GMT

Content-Type: text/html; charset=UTF-8

<html>...</html>

此图标表示小贴士、建议或注意事项。

此图标表示警告或提示。

中文版书中切口处的“ ”表示原书页码，便于读者与原英文版图书对照阅读，本书的索引所列页码为原英文版页码。

使用代码示例

本书是要帮助你完成任务。总的来说，用户可以在程序和文档中使用书中的代码，无须联系我们获得许可，除非是要复制大部分代码。举例来说，写个程序，其中使用了几段书中的代码，这无须获得许可。销售或分发O’Reilly图书的示例CD-ROM需要获得许可。在回答问题时引用本书及示例代码无须获得许可。在你自己的产品文档中使用大量本书的示例代码需要获得许可。

如果能标明出处，我们将十分感激，但这不是必需的。通常这包括标题、作者、出版社和ISBN。例如：“RESTful WebServices Cookbook by Subbu Allamaraju. Copyright 2010 Yahoo!, Inc.,978-0-596-80168-7。”

如果你觉得自己对示例代码的使用超出了正常使用范畴或不在此处给予的许可范围内，请通过[e-mail]联系我们。

Safari®在线图书

Safari Books Online是一个按需索取的电子图书馆，让你能够轻松地在超过7500本技术及创新参考书和视频中进行检索，快速找到你需要的答案。

订阅之后，你可以在我们的在线图书馆中阅读图书并观看视频。在你的手机或移动设备上读书。在印刷前看到新标题，独家阅读撰写中的原稿，向作者进行反馈。复制粘贴代码示例，管理你的收藏，下载章节，在关键部分加上书签，添加笔记，打印页面，并从大量其他省时的特性中获益。

O’Reilly Media已将本书英文版上传至SafariBooks Online。想访问本书或其他来自O’Reilly和其他出版商的类似主题，可以在（http://my.safaribooksonline.com）进行免费注册。

如何联系我们

请将对本书的评价和存在的问题通过如下地址告知出版者：

美国：

O’Reilly Media, Inc.

1005 Gravenstein Highway North

Sebastopol, CA 95472

中国：

北京市西城区西直门南大街2号成铭大厦C座807室（100035）

奥莱利技术咨询（北京）有限公司

O’Reilly的每一本书都有专属网站，你可以在那找到关于本书的相关信息，包括勘误列表、示例代码以及其他的信息。本书的网站地址是：

http://www.oreilly.com/catalog/9780596801687/

或者：

http://www.restful-webservices-cookbook.org

对于本书的评论和技术性的问题，请发送电子邮件到：

[e-mail]

关于本书的更多信息、会议、资料中心和O’Reilly网络，请访问以下网站：

http://www.oreilly.com/

http://www.oreilly.com.cn/

致谢

本书得到了很多人的帮助。O’Reilly的Mary Treseler，作为本书的编辑，她通过提出正确的问题帮助完善了本书的大纲，还提供了很多必要的支持、鼓励和礼貌的劝说，这才让想法化为现实。

非常感谢Mark Nottingham和Hugo Haas帮我起草了本书大纲的初稿。

Mike Amundsen，他为本书贡献了部分内容，花费了大量时间，用了很多红笔逐行审阅本书并做了批注。他的那些改善本书质量的建议是无价的。尽管他很忙，但Mike总是随叫随到来讨论书中解决方案和真实世界里各种权衡的利弊。

感谢Havi Hoffman，Yahoo! Press的管理者，他很耐心地指导我编写提案，避免陷入精耕细作之中。感谢Neal Sample，James Lok，Jay Rossiter和Tony Ng（全来自Yahoo! Inc.）在本书的撰写过程中给予的支持。还要感谢Korby Parnell为本书的编写出谋划策。

我要衷心地感谢Mark Nottingham，Eben Hewitt，Colin Jack，Stefan Tilkov，Norbert Lindenberg，Chris Westin，Dan Theurer，ShaunakKashyap，Larry Cable，Alan Dean，Surya Suravarapu，JimD’Ambrosia，Randolph Kahle，DhananjayNene和Brian Sletten，感谢他们对书中材料的明确性、相似性、质量和精确性提出有价值且具批判性的反馈。

感谢REST-Discuss Yahoo! Group（http://tech.groups.yahoo.com/group/rest-discuss）的成员，感谢他们对所有REST相关的内容进行的热烈、精彩且深刻的讨论。

还要感谢所有为本书草稿提出反馈的读者。

Mike Amundsen的贡献

Mike Amundsen贡献了4.1节、4.3节、6.1节、6.4节、9.1节、9.4节、9.5节、11.8节、11.9节、11.12节和附录D。

目 录

第1章 使用统一接口 1

1.1 如何保持交互的可见性 2

1.2 何时需要权衡可见性 4

1.3 如何维护应用程序状态 6

1.4 如何在服务器端实现安全和幂等的方法 9

1.5 如何在客户端处理安全和幂等方法 12

1.6 何时使用GET方法 13

1.7 何时使用POST方法 15

1.8 如何使用POST方法创建资源 17

1.9 何时使用PUT方法创建新资源 19

1.10 如何使用POST方法实现异步任务 20

1.11 如何使用DELETE方法实现异步删除 23

1.12 何时使用自定义HTTP方法 24

1.13 何时及如何使用自定义HTTP标头 26

第2章 识别资源 29

2.1 如何从领域名词中识别资源 30

2.2 如何选择资源粒度 31

2.3 如何将资源组织为集合 32

2.4 何时将资源合并为复合资源 35

2.5 如何支持计算或处理函数 37

2.6 何时及如何使用控制器来操作资源 40

第3章 设计表述 45

3.1 如何使用实体头来注解表述 46

3.2 如何解释实体头 50

3.3 如何避免字符编码不匹配 51

3.4 如何选择表述格式和媒体类型 52

3.5 如何设计XML表述 56

3.6 如何设计JSON表述 58

3.7 如何设计集合表述 59

3.8 如何保持同构的集合 61

3.9 如何在表述中使用可移植的数据格式 63

3.10 何时使用实体标识符 65

3.11 如何在表述中编码二进制数据 66

3.12 何时以及如何提供HTML表述 68

3.13 如何返回错误 70

3.14 如何在客户端处理错误 74

第4章 设计URI 77

4.1 如何设计URI 77

4.2 如何将URI用做模糊标识符 81

4.3 如何让客户端将URI视为模糊标识符 83

4.4 如何保持酷的URI 85

第5章 Web链接 88

5.1 如何在XML表述中使用链接 89

5.2 如何在JSON表述中使用链接 92

5.3 何时以及如何使用链接标头 93

5.4 如何分配链接关系类型 94

5.5 如何使用链接来管理应用程序的流程 97

5.6 如何处理临时URI 101

5.7 何时以及如何使用URI模板 103

5.8 如何在客户端使用链接 105

第6章 Atom和AtomPub 108

6.1 如何利用Atom建模资源 109

6.2 何时使用Atom 113

6.3 如何使用AtomPub服务和分类文档 117

6.4 如何针对Feed和Entry资源使用AtomPub 119

6.5 如何使用媒体资源 122

第7章 内容协商 125

7.1 如何标明客户端偏好 126

7.2 如何实现媒体类型协商 128

7.3 如何实现语言协商 129

7.4 如何实现字符编码协商 131

7.5 如何支持压缩 132

7.6 何时以及如何发送Vary头 133

7.7 如何处理协商失败 134

7.8 如何使用代理驱动的内容协商 136

7.9 何时支持服务器驱动的协商 137

第8章 查询 139

8.1 如何针对查询设计URI 139

8.2 如何设计查询响应 142

8.3 如何支持有大量输入的查询请求 144

8.4 如何存储查询 146

第9章 Web缓存 149

9.1 如何设置过期缓存头 150

9.2 何时设置过期缓存头 153

9.3 何时以及如何在客户端使用过期缓存头 156

9.4 如何支持复合资源的缓存 157

9.5 如何保持新鲜且温暖的缓存 158

第10章 条件请求 161

10.1 如何生成Last-Modified和ETag头 163

10.2 如何在服务器端实现条件GET请求 164

10.3 如何从客户端提交条件GET和HEAD请求 167

10.4 如何在服务器端实现条件PUT请求 169

10.5 如何在服务器端实现条件DELETE请求 173

10.6 如何从客户端发起无条件GET请求 175

10.7 如何从客户端提交条件PUT和DELETE请求 176

10.8 如何使POST请求条件化 178

10.9 如何生成一次性URI 181

第11章 其他内容 184

11.1 如何复制资源 185

11.2 如何合并资源 187

11.3 如何移动资源 189

11.4 何时使用WebDAV方法 191

11.5 如何支持跨服务器的操作 193

11.6 如何获取资源的快照 195

11.7 如何撤销资源更新 198

11.8 如何为部分更新提炼资源 200

11.9 如何使用PATCH方法 203

11.10 如何批量处理相似的资源 206

11.11 如何触发批量操作 209

11.12 何时使用POST来合并多个请求 211

11.13 如何支持批量请求 215

11.14 如何支持事务 217

第12章 安全 220

12.1 如何使用基本身份验证来验证客户端 221

12.2 如何使用摘要身份验证来验证客户端 224

12.3 如何使用三方OAuth 226

12.4 如何使用两方OAuth 232

12.5 如何处理URI中的敏感信息 235

12.6 如何维护表述的机密性与完整性 237

第13章 可扩展性与版本控制 239

13.1 如何维持URI的兼容性 240

13.2 如何维持XML和JSON表述的兼容性 242

13.3 如何扩展Atom 245

13.4 如何维持链接的兼容性 249

13.5 如何实现支持可扩展性的客户端 250

13.6 何时需要版本化 251

13.7 如何版本化RESTful Web服务 252

第14章 服务发现 256

14.1 如何编写RESTful Web服务的文档 256

14.2 如何使用OPTIONS 259

附录A 辅助读物 261

附录B REST概述 265

附录C HTTP方法 268

附录D AtomSyndication Format 273

附录E 链接关系类型 279

索引 287