RESTful Web APIs中文版

近年来，REST的流行导致了各种“RESTful”API的巨大增长，但是这些API却错失了很多架构的好处。通过这本实用指南，你将可以学习到如何设计可用的，并能随着时间不断进化的REST API。通过专注于跨多种领域的解决方案，本书向你展示了该如何使用那些为世界上成功的分布式计算系统——万维网而设计的工具，从而来 创建强大且安全的应用。你将探索REST背后的概念，学习多种可用于创建基于超媒体API的策略，并在本书一步步的指导下整合你所学到的所有内容，从而去设计RESTful的web API。

√ 审查了包括集合模式和纯超媒体在内的API设计策略。

√ 理解如何将超媒体与表述整合进一个一致的API。

√ 探索XMDP和ALPS profile格式是如何帮助你应对web API的“语义挑战”的。

√ 学习近二十多种标准化的超媒体数据格式。

√ 应用在API实现中使用HTTP的实践。

√ 使用JSON-LD标准及其他Linked Data方法来创建web API。

√ 理解在嵌入式系统使用REST的CoAP协议。

《RESTful Web APIs中文版》是针对RESTful API的实用指南，通过展示各种用来创建高可用应用的强大工具，讲解REST的深层原理，以及介绍基于超媒体API的策略，使读者得以在将上述内容融会贯通后，设计出让客户高度满意的RESTful的web API。本书极具专业性与前瞻性，既代表了API领域的前沿趋势，也覆盖了API领域的重要实践。

Leonard Richardson， 《Ruby Cookbook》 （O’Reilly）一书的作者，曾 创建了包括Beautiful Soup在内 的多个开源代码库。Mike Amundsen 是包括《Building Hypermedia APIs with HTML5 and Node》（O’Reilly） 在内的十几本为人所称道的技术图书的作者。

序
前言
第1章 网上冲浪
场景1：广告牌
资源和表述
可寻址性
场景2：主页
短会话（Short Session）
自描述消息（self-descriptive message）
场景3：链接
标准方法
场景4：表单和重定向
应用状态（Application State）
资源状态（resource state）
连通性（connectedness）
与众不同的Web
Web API落后于Web
语义挑战
第2章 一个简单的API
第3章 资源和表述
第4章 超媒体
第5章 领域特定设计
第6章 集合模式（Collection Pattern）
第7章 纯-超媒体设计
第8章 Profile
第9章 API设计流程
第10章 超媒体动物园
第11章 API中的HTTP
第12章 资源描述和Linked Data
第13章 CoAP：嵌入式系统的REST
附录
词汇表

“大多数软件系统在创建时都有一个隐含的假设：整个系统处在一个实体的控制之下；或者至少参与到系统中的所有实体都向着一个共同目标行动，而不是有着各自不同的目标。当系统在互联网上开放地运行时，无法安全地满足这样的假设。”
——RoyFielding
ArchitecturalStylesandtheDesignofNetwork-basedSoftwareArchitectures“Discordia信徒应该一直使用官方的Discordian文档编号系统。”
——MalaclypsetheYounger和LordOmarKhayyamRavenhurst
我要向你展示一种可以更好地进行分布式计算的方式，它使用了有史以来最成功的分布式系统，即万维网的根本思想。如果你已经决定（或者你的经理已经决定）需要为你的公司发布一个webAPI的话，我希望你能够读一下这本书。不管在你计划中的是一个公共的API，还是一个纯粹的内部API，抑或是一个只有受信伙伴可以访问的API——它们都可以从REST的哲学中受益。
如果你想学习如何编写API客户端的话，那么这本书对你来说并不是必要的。这是因为大多数现有的API设计都基于一些有着数年之久的假设，而这些假设正是我想要摧毁的。
大部分今天的API都有着一个很大的问题：一旦部署，它们将无法改变。有一些大名鼎鼎的API会在一次部署后多年保持静态不变，即使围绕它们的行业发生着改变，这是因为要改变它们非常困难。
但是RESTful架构是为掌控变化而设计的。万维网由数百万的网站组成，运行在数千种不同的服务器实现之上，并且经历着周期性的重新设计。这些网站被数十亿的用户访问着，而这些用户使用着几十种硬件平台之上的数百种不同的客户端实现。你的部署在一开始可能看上去不会如此混乱，但是当你的应用越发接近web的规模时，你将会看到越发相似的混乱景象。
要改变一个非常简单的系统通常都是很容易的。在规模很小时，一个RESTful系统比一个一键式的解决方案（push-buttonsolution）需要花费更多预支的设计成本。但是当你的API逐渐成熟并开始发生变化时，你将会真正需要一些像REST这样的方式来应对变化。
y一个商业上成功的API将保持连续多年的可用。一些API拥有数百甚至是数以千计的用户。就算问题域只是偶然地发生变化，对客户端带来的累积效应将是非常大的。
y有一些API一直都在发生变化，新的数据元素和业务规则不断地被添加进来。
y在某些API中，每个客户端都可以通过改变工作流来使其适合自己的需求。即使API自身从不变化，每个客户端对API的经历（鉴于经历不同的工作流）将会不同。
y编写API客户端的人通常不会和编写服务器的人隶属于同一个团队。所有向公共开放的API都属于这一类。
如果你不知道外部的客户端是哪种类型的话，你需要在做出变化时格外小心——否则你就需要一个能够在发生变化时保证不会破坏所有客户端的设计。如果你为你的API复制了现有的设计，你将很可能只是在重复以往犯过的错误。不幸的是，大部分的改进发生在幕后，它们大都还处于实验阶段并需要经过漫长的标准流程。我将会在本书中讨论到数十种特定的技术，包括很多还仍然处于开发之中。但是我的主要目标是要教会你REST的基本原则。通过对这些内容的学习，你将可以对任何实验成果以及那些通过流程审核的标准善加利用。
这里有两个我想在本书中尝试解决的具体问题：重复的工作以及对超媒体的逃避。让我们来看看它们。
重复的工作
现今已发布的API都是根据托管它们的公司的名字进行命名的。我们谈论着“TwitterAPI”、“FacebookAPI”和“Google+API”。这三套API做着相似的事情。它们都拥一些用户账户的概念，（在其他方面）它们都允许用户向自己的账户发布文本信息。但是每个API都具有完全不同的设计，学习一个API并不能帮助你学习下一个。当然，Twitter、Facebook和Google都是互相竞争的大型公司，它们并不想让你很容易地就学会它们竞争对手的API。但是小公司和非营利性组织也在做着相同的事。它们重新设计着自己的API，就好比从来没有人在这方面有过相似的想法一样，但是这干扰了它们想让人们实际使用它们的API的目标。
让我来向你展示一个例子吧。网站ProgrammableWeb（http：//www。programmableweb。com/）拥有着一个超过8000个API的目录。当我正在编写此书之时，它已经收录了57种微博API——这些API的主要用途是向用户的账户发布文本信息注2。很不错，有57家公司在这个领域发布了API，但是我们真的需要57种不同的设计吗？我们在这里讨论并不是那些复杂难懂的业务，例如保险政策或法规守则，我们讨论的只是向用户账号发布少量的文本信息。你想成为那个设计第58种微博API的人吗？
最显而易见的解决方案便是创建一个微博API的标准。但是我们已经有了一个可以很好工作的标准：Atom发布协议（AtomPublishingProtocol）。它发布于2005年，然而几乎没有人使用它。有一些关于API的原因，使得每个人都想从头开始设计他们自己的API，即使从业务的角度来看这并没有什么意义。
我不认为凭我一个人的力量就能结束这种无用功，但是我确实认为可以将问题分解成若干有意义的小块，然后提供一些方式来让新的API可以复用已经完成的这些工作。
超媒体很难
早在2007年，LeonardRichardson和SamRuby编写了本书的前身，RESTfulWebServices(O‘Reilly)。那本书同样也尝试于解决两个大的问题。其中一个问题已经被解决，而另一个却没有任何进展。
第一个问题是：在2007年，在API设计的多个阵营中，REST学派正在与使用基于SOAP等重量级技术的对手学派进行对峙，他们忙于应对来自对方的对REST学派合理性的质疑。RESTfulWebServices一书的出现打破了这种对峙的僵局，有效地为RESTful设计原则防御了来自SOAP学派的进攻。
很好，这场对峙已经结束，而REST赢得了胜利。SOAPAPI仍在被使用着，不过仅限于那些起初支持SOAP学派的大公司。几乎所有面向公众的API口头上都说自己遵守了RESTful原则。
这又将我们带到了第二个问题：REST并不只是一个技术词汇——它同样还是一个营销术语。在很长一段时间里，REST成了一个口号，它象征着任何站在SOAP学派对立面的势力。任何没有使用SOAP的API都将自己标榜为REST，即使它的设计与REST毫无关系甚至是违背了REST的基本原则。这样做是错误的，是令人困惑的，它给REST这个技术词汇带来了一个坏名声。
这种情况自2007年便有了较大的改善。每当我审视那些新的API，我看到了开发者们的工作，可以看得出，这些开发人员是理解那些我将在本书前几章中解释的概念的。今天大部分举着REST大旗的开发者都理解资源和表述，理解如何使用URL来为资源命名，以及如何正确地使用HTTP方法。因此本书的前三章将不需要做过多的事情，只需让新的开发者加速赶上我们即可。
但是在REST中，还有一个方面令大部分的开发人员仍然无法理解，即：超媒体。我们都理解Web环境中的超媒体。它只是作为代表链接的一个华丽的词汇。网页经过互相的链接，随即产生了万维网，万维网便是由超媒体驱动的。但是，貌似只要在webAPI中涉及到超媒体，我们便有了心理障碍。这是一个大问题，因为超媒体是一项能让webAPI优雅处理变化的特性。
从RESTfulWebAPIs一书的第４章开始，我的首要目标便是教会你超媒体的工作原理。如果你从未听到过这个词，我将会结合其他重要的REST概念向你讲授该词。如果你听到过超媒体，但是这个概念吓到了你，我将会尽我所能来为你建立勇气。如果你无法将超媒体装进你的大脑，我将会以各种我所能想到的方式来向你展示超媒体，直到你记住并理解它。
RESTfulWebServices一书也涉及到了超媒体，但是这并不是该书的重心所在。就算跳过该书的超媒体部分也可以照样设计出一个功能性的API。相比之下，RESTfulWebAPIs则是一本真正有关超媒体的书。
我之所以这样做是因为超媒体是REST最重要的一个方面，也是最不被理解的一个方面。在我们完全理解超媒体之前，REST将会被继续视为一个营销术语，而不是对处理分布式计算复杂性的一次认真的尝试。
……