前言

本书围绕Web API 展开,旨在帮助读者了解在开发Web API 的过程中应如何设计,以及需要注意哪些地方等。

现在,开发人员必须设计、开发Web API 的情况越来越多,不仅各个服务之间集成与协作的需求越来越常见,而且移动应用和其后端也面临着同样的情形,游戏方面和后端进行交互的情况也在增多。另外,JSON 以及XML 技术已成为大多数Web 应用之间进行非同步通信的首选,因此可以说Web API 的开发正在成为互联网以及Web 相关技术人员的必修科目。然而,现状却不太理想,很多Web 开发人员甚至只知道返回JSON 的API。

笔者作为独立的开发人员曾参与过各种各样的IT 项目,其中有很多项目都引入了Web API 的设计与开发。本书的内容就是围绕着笔者在那些实践中做过的研究、受到的挫折、思考的内容写成的,目的是向想要学习API 设计的开发人员介绍API设计的思路与方法。

本书的内容虽不算多,却由于笔者的懈怠,从立项开始直至收笔整整用了两年时间。在这期间,Web API 所涉及的大环境已经发生了剧变,出现了Apigee ①(http://apigee.com/)、3scale②(http://www.3scale.net/)等提供Web API 相关服务的在线服务,APIcon 等以API 为主题的国际性大会也开始频繁召开。可以说,开发并公开API越来越重要,也引起了人们越来越多的关注。当然,幸运的是,本书出版的意义也增加了不少。

① 一家致力于API 网关服务的云计算公司,成立于2004 年,在2016 年12 月被Google 公司收购。—译者注
② 一家提供API 网关平台管理服务的云计算公司,在2016 年6 月被Redhat 公司收购。—译者注

话虽如此,同国外相比,目前日本国内的在线服务似乎很少有公开Web API 的。而那些已经公开的API,也一般实施拿来主义,很多案例都是直接参考国外类似服务的API 设计,其粗制滥造可见一斑。另外,最近几年国外关于API 设计的讨论异常火热,但对于使用日语、在日本生活的日本人而言,总有一些信息无法接触到①。因此也就造成了不同地方的人们为了应对相同的问题而绞尽脑汁、反复验证,进行了很多重复劳动。

编写本书的目的之一也是希望多少能够为改变这样的现状而贡献绵薄之力。Web API 的相关规则、趋势以及设计规范等会随着时代前进的步伐不断变化。那些以后需要从事Web API 设计与开发的技术人员,如果能够通过本书了解Web API 相关的基础知识,并在此基础上进一步搜集相关信息,从而开发出更优秀的API,那实在是本书所幸。

① 中国国内也是类似的情况。—译者注

目标读者

本书面向从事Web API 设计与开发的技术人员,以及负责使用或维护现有WebAPI 的软件开发人员。由于本书不会详细展开开发相关的基础知识等,因此需要读者具备一定的开发基础。

本书涉及的内容不囿于某个具体的编程语言。换言之,本书不会提及如何使用某一特定的语言或框架来实现Web API 等内容。因此,当需要了解特定编程语言的实现时,读者需要阅读相关的入门书或在网络上检索相关信息等。

本书中引用或提及的网络上的信息,如果原始资料是英文的,将附上URI,以标明出处。与之对应的中文翻译、中文解释说明等,还请读者自行检索,不再赘述。

本书的结构

各章概要如下所示。

第1 章 什么是Web API

第1 章作为开篇,介绍了Web API 的现状以及灵活使用本书内容的方法。在技术人员想要公开Web API 时,也可以以这部分内容为理论依据来说服自己的上司。

第2 章 端点的设计与请求的形式

Web API 遵循Web 的相关语法,由请求与响应构成。第2 章就将重点介绍其中的请求方式,即如何设计客户端对服务器的访问请求等相关内容。所谓请求方式,包括从客户端向服务器发送信息的方法,以及接收信息的服务器端的端点(URI)的设计。

第3 章 响应数据的设计

第3 章将介绍针对请求所返回的响应数据(Response Data)的结构及其相关设计思想。这里将会涉及应该选择什么样的数据格式、发生错误时该如何处理等话题。

第4 章 最大程度地利用HTTP 协议规范

Web API 通过HTTP 协议进行数据的传输。在第4 章中,我们将对HTTP 协议规范进行详细剖析,思考如何将该协议规范更好地体现在API 里。

第5 章 开发方便更改设计的 Web API

并非一旦公开发布,Web API 的所有开发工作便就此完结了。一般还需根据所提供的服务的变更、周边环境的变化,对已发布的API 进行维护更新。但是,倘若突然对已发布的API 进行“大手术”,很有可能导致那些正在使用API 的客户端出错。第5 章将围绕如何修改已发布的API 这一话题进行讨论。

第6 章 开发牢固的Web API

在互联网上公开发布的Web API 有可能会遇到预设之外的非法访问。第6 章中将探讨如何尽可能减小这类非法访问所带来的危害,以及相关的安全性和稳定性等话题。

附录 A 公开Web API 的准备工作

关于Web API,除了其设计之外,还有很多需要做的工作。在附录A 中,我们将简单介绍一下API 设计之外的相关工作的内容。

附录B Web API 确认清单

附录B 中将给出Web API 的确认清单,读者能够依照此清单检查自己所设计的Web API 是否符合本书提到的相关要点。

读者意见与提问

虽然笔者已经尽最大努力对本书的内容进行了验证与确认,但仍不免在某些地方出现错误或者容易引起误解的表达等,给读者的理解带来困扰。如果读者遇到这些问题,请及时告知,我们在本书再版时会将其改正,在此先表示不胜感激。与此同时,也希望读者能够为本书将来的修订提出中肯的建议。本书编辑部的联系方式如下①。

株式会社O’reilly Japan

〒 160-0002 东京都新宿区坂町26 号Intelligent Plaza 大厦1F

电话 03-3356-5227

FAX 03-3356-5261

电子邮件 japan@oreilly.co.jp

本书的主页地址如下。

http://www.ituring.com.cn/book/1583

http://www.oreilly.co.jp/books/9784873116860(日语)

http://takaaki.info/web-api-the-good-parts ( 作者)

关于O’Reilly 的其他信息,可以访问下面的O’Reilly 主页查看。

http://www.oreilly.com/( 英语)

http://www.oreilly.co.jp/(日语)

表述规则

本书在表述上采用如下规则。

粗体字(Bold)

用来表示新引入的术语、强调的要点以及关键短语。

① 此联系方式仅支持日语版图书,读者可以在图灵社区的本书主页(http://www.ituring.com.cn/book/1583)发表评论、提交勘误等。—编者注

等宽字(Constant Width)

用来表示下面这些信息:程序代码、命令、序列、组成元素、语句选项、分支、变量、属性、键值、函数、类型、类、命名空间、方法、模块、属性、参数、值、对象、事件、事件处理器、XML 标签、HTML 标签、宏、文件的内容、来自命令行的输出等。若在其他地方引用了以上这些内容(如变量、函数、关键字等),也会使用该格式标记。

等宽粗体字(Constant Width Bold)

用来表示用户输入的命令或文本信息。在强调代码的作用时也会使用该格式标记。

等宽斜体字(Constant Width Italic)

用来表示必须根据用户环境替换的字符串。

用来表示提示、启发以及某些值得深究的内容的补充信息。

表示程序库中存在的bug 或时常会发生的问题等警告信息,引起读者对该处内容的注意。

关于示例代码的使用

本书旨在对读者的日常工作有所帮助。因此一般而言,读者将书中示例代码用于自己的程序、文档均不存在任何问题。在多数情况下,无需得到我们的许可,即可对本书的代码进行转载。例如,可以将本书某部分代码应用于自己编写的程序不用向我们提出申请。然而,如果想将本书中的示例代码编篡成册,制作成CD-ROM并销售的话,则必须得到我们的授权。而如果是引用本书及书中示例代码来答疑等,我们则不加任何限制。但是,一旦需要将本书绝大部分代码以手册的形式进行传播,就必须得到我们的许可。

虽然我们并不要求读者在引用本书的部分代码时标明出处,但若你能做到,我们将深表感激。引用时请给出作者名、译者名、书名、出版社、ISBN 等信息。

读者在使用本书示例代码时,如果发现所使用的情形超出了我们给出的许可范围,请及时联系japan@oreilly.co.jp。

致谢

首先要感谢时时对进度缓慢的笔者进行鞭策,并极富耐心地等待笔者交稿的O’Reilly Japan 公司的伊藤先生和宫川先生。

接着,向执笔期间给笔者诸多帮助和照顾的妻子,以及在笔者夫妇忙碌得腾不出手时不厌其烦地伸出援手的父母,在此一并表示由衷的感谢。

另外,也要感谢参与本书审阅并给出大量宝贵建议的ma.la 先生、石田武士先生、关根裕纪先生、近泽良君、多久岛信隆先生、上杉隆史先生、池徹先生等。

正是有了大家的鼎力相助,本书才得以完成,这里再次向各位表示衷心的感谢!

目录

  • 译者序
  • 前言
  • 第1章 什么是Web API
  • 第2章 端点的设计与请求的形式
  • 第3章 响应数据的设计
  • 第4章 最大程度地利用HTTP协议规范
  • 第5章 开发方便更改设计的Web API
  • 第6章 开发牢固的Web API 
  • 附录A 公开Web API的准备工作
  • 附录B Web API确认清单