ASP.NET Web API设计

如何为浏览器和移动设备等多客户端设计和构建可演化Web API？本书以ASP.NET Web API框架为例，系统介绍了相关的理论和工具，让读者全面掌握设计和实现可演化Web API的技术。
《ASP.NET Web API设计》主要面向有经验的.NET开发人员。不过，书中关于Web API基础理论和设计的内容同样适用于Java、Ruby、PHP和Node等开发者。

《ASP.NET Web API设计》依托ASP.NET Web API阐述API设计与开发的通用技术，是一本全面介绍如何构建真实可演化API的实践指南。本书共分三部分。第一部分介绍Web/HTTP和API开发的基础知识，介绍ASP.NET Web API，为初学者以及想充分利用HTTP的读者建立好的起点。第二部分完整介绍了真实Web应用程序的开发，其内容从设计讲到实现，全面覆盖客户端与服务器端开发。第三部分深入ASP.NET Web API的内部机制，并讲解一些高级的主题（如安全和可测试性），加深你的理解，让读者学会更好地利用Web API构建可演化系统。

Glenn Block，曾任职微软，推动了ASP.NET Web API早期版本的开发。
Pablo Cibraro，拥有十余年使用微软技术设计和实现大型分布式系统的经验。
Pedro Félix，是一位软件工程师和教授，研究方向为基础设施实现、用户身份管理，以及访问控制。
Howard Dierking，是微软ASP.NET Web API团队的产品经理，当前的工作重点包括NuGet和Katana项目。
Darrel Miller，是Tavis软件公司的创始人之一，帮助人们学习如何在业务应用中采用REST架构风格。

★“这本书提供了及时而全面的指南，帮助人们使用ASP.NET Web API构建坚实的系统，融合了ASP.NET Web API团队的经验与软件业界多年的专业积累。”
——Scott Guthrie 微软“云和企业”副总裁

★“第一次获悉本书时，我就急切地想读，原因有二。首先，我当前的工作中涉及为应用设计API以使之与多种系统交互。其次，是因为本书的一位作者——Glenn Block，我认识他有段时间了，我见过他，与他有过对话，读了他的大量博文，我确定本书不会让人失望，而事实证明确实如此。”
——Joseph Guadagno 亚利桑那Southeast Valley .NET用户组创始人

作者简介
关于封面图
序
前言
第一部分基础知识
第1章因特网、万维网和HTTP协议
1.1Web体系结构
1.1.1资源
1.1.2URI
1.1.3酷URI
1.1.4表示
1.1.5媒体类型
1.2HTTP协议
1.2.1HTTP 1.1之后
1.2.2HTTP消息交换
1.2.3中间层
1.2.4中间层类型
1.2.5HTTP方法
1.2.6标头
1.2.7HTTP状态码
1.2.8内容协商
1.2.9缓存
1.2.10身份验证
1.2.11身份验证方案
1.2.12附加身份验证方案
1.3小结
第2章Web API
2.1什么是Web API
2.2SOAP Web服务
2.3Web API的起源
2.4Web API革命开始
2.5关注Web
2.6Web API指南
2.7特定领域的媒体类型
2.8媒体类型档案
2.9多个表示
2.10API 风格
2.10.1Richardson成熟度模型
2.10.2RPC（RMM 第0级）
2.10.3资源（RMM 第1级）
2.10.4HTTP 谓词（RMM 第2级）
2.10.5以资源为中心的API
2.10.6超媒体（RMM 第3级）
2.10.7REST
2.10.8REST约束
2.11小结
第3章ASP.NET Web API 101
3.1核心场景
3.1.1第一类HTTP编程
3.1.2对称的客户端和服务器编程体验
3.1.3对不同格式的灵活支持
3.1.4告别"尖括号编码"
3.1.5支持单元测试
3.1.6多种托管选项
3.2ASP.NET Web API入门
3.3新建Web API项目
3.3.1WebApiConfig
3.3.2ValuesController
3.4"Hello Web API!"
3.4.1创建服务
3.4.2客户端
3.4.3宿主
3.5小结
第4章处理架构
4.1托管层
4.2消息处理程序管道
4.3控制器处理
4.4小结
第二部分真实世界的API开发
第5章应用程序
5.1为什么要可演化
5.1.1演化的障碍
5.1.2代价是什么
5.1.3为什么不创建新版本
5.1.4付诸实践
5.2应用程序目标
5.2.1目标
5.2.2机会
5.3信息模型
5.3.1子域
5.3.2相关资源
5.3.3属性组
5.3.4属性组的集合
5.3.5信息模型与媒体类型
5.3.6问题集合
5.4资源模型
5.4.1根资源
5.4.2搜索资源
5.4.3集合资源
5.4.4个体资源
5.5小结
第6章媒体类型选择与设计
6.1自描述
6.2协议类型
6.3媒体类型
6.3.1原始格式
6.3.2流行格式
6.3.3新格式
6.3.4超媒体类型
6.3.5媒体类型爆炸
6.3.6通用媒体类型和档案
6.3.7其他超媒体类型
6.4链接关系类型
6.4.1语义
6.4.2替换嵌入资源
6.4.3间接层
6.4.4引用数据
6.4.5工作流
6.4.6语法
6.4.7完美结合
6.5设计新的媒体类型协议
6.5.1选择格式
6.5.2支持超媒体
6.5.3可选、强制、省略和适用
6.5.4嵌入元数据和外部元数据
6.5.5可扩展性
6.5.6注册媒体类型
6.6设计新的链接关系
6.6.1标准链接关系
6.6.2扩展链接关系
6.6.3嵌入链接关系
6.6.4注册链接关系
6.7问题跟踪域中的媒体类型
6.7.1list资源
6.7.2item资源
6.7.3discovery资源
6.7.4search资源
6.8小结
第7章构建API
7.1设计
7.2获得源代码
7.3使用行为驱动开发构建实现
7.4浏览解决方案
7.5软件包和程序库
7.6自托管
7.7模型和服务
7.7.1问题和问题库
7.7.2IssueState
7.7.3IssuesState
7.7.4Link
7.7.5LinkeStateFactory
7.7.6LinkFactory
7.7.7IssueLinkFactory
7.8验收标准
7.9功能：获取问题
7.9.1获取一个问题
7.9.2获取未关闭的和已关闭的问题
7.9.3获取不存在的问题
7.9.4获取所有问题
7.9.5获取所有问题的Collection+Json表示
7.9.6搜索问题
7.10功能：创建问题
7.11功能：更新问题
7.11.1更新一个问题
7.11.2更新不存在的问题
7.12功能：删除问题
7.12.1删除一个问题
7.12.2删除不存在的问题
7.13功能：处理问题
7.13.1测试
7.13.2实现
7.14小结
第8章改进API
8.1新功能的验收标准
8.2实现输出缓存支持
8.3添加输出缓存测试
8.4实现缓存重验证
8.5为缓存重验证实现条件GET
8.6冲突检测
8.7实现冲突检测
8.8变更审计
8.9使用Hawk认证实现变更审计
8.10跟踪
8.11实现跟踪
8.12小结
第9章构建客户端
9.1客户端程序库
9.1.1封装库
9.1.2链接用作函数
9.2应用程序工作流
9.2.1用户需知
9.2.2带有使命的客户端
9.2.3客户端状态
9.3小结
第三部分Web API细节
第10章HTTP编程模型
10.1消息
10.2标头
10.3消息内容
10.3.1使用消息内容
10.3.2创建消息内容
10.4小结
第11章托管
11.1Web托管
11.1.1ASP.NET基础结构
11.1.2ASP.NET路由
11.1.3Web API路由
11.1.4全局配置
11.1.5Web API ASP.NET处理程序
11.2自托管
11.2.1WCF 架构
11.2.2HttpSelfHostServer类
11.2.3HttpSelfHostConfiguration类
11.2.4URL 预留和访问控制
11.3用OWIN和Katana托管Web API
11.3.1OWIN
11.3.2Katana项目
11.3.3Web API配置
11.3.4Web API中间件
11.3.5OWIN生态环境
11.4内存托管
11.5Azure Service Bus Host
11.6小结
第12章控制器和路由
12.1HTTP消息流概览
12.2消息处理程序管道
12.2.1分发程序
12.2.2HttpControllerDispatcher
12.2.3控制器选择
12.2.4控制器激活
12.3控制器管道
12.3.1ApiController
12.3.2ApiController 处理模型
12.4小结
第13章格式化程序和模型绑定
13.1ASP.NET Web API中模型的重要性
13.2模型绑定如何工作
13.3内建的模型绑定器
13.3.1ModelBindingParameterBinder
13.3.2值提供程序
13.3.3模型绑定器
13.3.4只对URI进行模型绑定
13.3.5FormatterParameterBinder实现
13.3.6HttpParameterBinding的默认选择
13.4模型验证
13.4.1将数据标记属性用于模型
13.4.2查询验证结果
13.5小结
第14章HttpClient
14.1HttpClient类
14.1.1生存周期
14.1.2封装类
14.1.3多个实例
14.1.4线程安全
14.1.5辅助方法
14.1.6抽丝剥茧
14.1.7完成的请求无异常
14.1.8内容为王
14.1.9取消请求
14.1.10SendAsync
14.2客户端消息处理程序
14.2.1代理处理程序
14.2.2伪响应处理程序
14.2.3创建可以重用的响应处理程序
14.3小结
第15章安全
15.1传输安全
15.2在ASP.NET Web API中使用TLS
15.2.1IIS 托管时使用TLS
15.2.2自托管时使用TLS
15.3身份验证
15.3.1声明模型
15.3.2获取和设置当前用户对象
15.3.3基于传输的身份验证
15.3.4服务器身份验证
15.3.5客户端身份验证
15.3.6HTTP身份验证框架
15.3.7实现基于HTTP的身份验证
15.3.8Katana身份验证中间件
15.3.9主动和被动的身份验证中间件
15.3.10Web API身份验证筛选器
15.3.11基于令牌的身份验证
15.3.12Hawk身份验证方案
15.4授权
15.4.1授权执行
15.4.2跨域资源共享
15.4.3ASP.NET Web API 的CORS支持
15.5小结
第16章OAuth 2.0授权框架
16.1客户端应用程序
16.2访问受保护资源
16.3获得访问令牌
16.4授权码授予
16.5范围
16.6前通道与后通道
16.7刷新令牌
16.8资源服务器和授权服务器
16.9在ASP.NET Web API中处理访问令牌
16.10OAuth 2.0与身份验证
16.11基于范围的授权
16.12小结
第17章可测试性
17.1单元测试
17.1.1使用测试框架
17.1.2Visual Studio单元测试入门
17.1.3xUnit.NET
17.1.4单元测试在测试驱动开发中的作用
17.2对ASP.NET Web API实现进行单元测试
17.2.1测试ApiController
17.2.2测试MediaTypeFormmater
17.2.3单元测试HttpMessageHandler
17.2.4测试ActionFilterAttribute
17.3对路由进行单元测试
17.4ASP.NET Web API的集成测试
17.5小结
附录A媒体类型
附录BHTTP标头
附录C内容协商
附录D缓存实战
附录E身份验证工作流
附录Fapplication/issue+json媒体类型规范
附录G公钥加密和证书

为什么要阅读本书
Web API 开发呈现爆炸式增长。各家公司都在投资构建可以通过Web 使用多种客户端访问的系统。想想你经常光顾的网站，这些网站很可能已经提供了访问API。创建一个使用HTTP 进行通信的API 非常简单，而挑战在第一个版本部署后才会出现。实际上，HTTP协议的制定者对这个问题，以及如何设计可演化API 已经进行了周详的考虑。媒体类型和超媒体就是设计可演化API 的核心。但是，很多API 开发者并未对此加以考虑或利用，部署的API 没有合理地使用HTTP 协议，客户端严重依赖API 的具体实现。这样的API 很难进行演化，极易破坏客户端功能。为什么会出现这样的情况呢？因为人们经常觉得，从工程角度看，这是实现功能的最简单、最直接的做法。但是，从长期看，这种做法违反直觉，与Web 自身的基本设计原则背道而驰。
本书的目标读者是希望设计出适应长期变化的API 的开发者。变化是不可避免的：你今天构建的API 将会演化。因此，问题不是"要不要"，而是"如何"设计可演化的API。你在项目早期做出的决定（或者未做出的决定）会极大地影响以下问题的答案。
添加一个新功能，会破坏现有的客户端，强制现有客户端升级并重新部署吗？或者，现有客户端还能继续工作？
如何保障API 的安全？能够使用较新的安全协议吗？
API 可以扩展规模，满足用户需求吗？或者必须重新进行架构设计？
能够支持未来出现的新客户端和新设备吗？
你在设计时可以考虑这些问题。初看起来，这似乎是预先做大量设计（Big Design Up Front）或者瀑布方法。其实不然。你不需要在构建系统前做出完备的设计，也不需要进行过度分析。有些决定的确需要预先做出，但这些决定处于较高的层次，关系到整体设计。要做出这些决定，你并不需要理解或预知系统的每个方面。实际上，这些决定奠定了迭代演化的基础，在随后构建系统时，你可以在此基础上，采取各种方式不断强化自己的目标。
本书更偏重应用而非理论。我们希望你读完本书之后，获得构建真实可演化系统的能力。为了达到这个目的，开篇将介绍Web 和Web API 开发的一些必知内容，然后从设计到实现，逐步介绍如何使用ASP.NET Web API 创建一个新API。这个API 的实现将覆盖一些重要的主题，例如：如何使用ASP.NET Web API 实现超媒体、如何执行内容协商。我们将演示这个API 在部署后如何实际进行演化，还将讨论如何使用既有实践（例如：验收测试、测试驱动开发）和技术（例如：控制反转）提高代码的可维护性。最后，我们将深入Web API 的内部，帮助你加深理解，更好地利用Web API 构建可演化系统。
预备知识
要充分理解本书的内容，你应该是一位开发人员，拥有使用.NET 3.5 或更高版本开发C#应用程序的经验。如果你还具有构建Web API 的经验，那就更好了。在开发API 时使用过哪种框架并不重要，重要的是应该熟悉相关的概念。阅读本书并不需要ASP.NET Web API或ASP.NET 经验，但熟悉ASP.NET MVC 的确会对你很有帮助。
如果你不是一位.NET 开发人员，那么本书也有适合阅读的内容。我们编写本书时设定了一个具体的目标，要使书中大部分内容关注API 设计和开发的通用技术，不与ASP.NETWeb API 直接相关。因此，我们认为，无论你的开发背景是什么（Java、Ruby、PHP、Node 等），都可以通过本书前两部分的大部分内容学习API 的开发。
漫游指南
在开始你的阅读旅程之前，这里有一些漫游本书内容的指南。
第一部分主要对Web API 开发进行介绍。这部分覆盖了Web/HTTP 和API 开发的基础知识，介绍ASP.NET Web API。如果你刚刚接触Web API 开发/ASP.NETWeb API，那么这部分是一个很好的开始。如果你已经在使用ASP.NET Web API （或其他Web API 框架），但是想更多地了解如何充分利用HTTP，这部分也是一个很好的起点。
第二部分关注真实世界的Web API 开发。这部分完整介绍了一个真实世界中Web应用程序的开发，从设计到实现，覆盖客户端和服务器。如果你已经对Web API开发颇为熟悉，希望很快开始构建应用程序，那么可以直接从第二部分开始阅读。
第三部分是一个相当全面的参考资料，详细介绍了ASP.NET Web API 各部分的内部机制。这部分还覆盖了一些较为高级的主题，例如：安全和可测试性。如果你已经在使用ASP.NET Web API 构建应用程序，希望了解如何将Web API 自身的功能发挥到极致，请从第三部分开始阅读。