Web API初接触

[XXHolic]

目录

• 想法
• 什么是 Web API
• 需要设计 API 的场景
• 公开 Web API 的重要性
• 优美 Web API 的几个特性
• 如何设计开发 Web API
• 两个重要原则
• 自己的一点思考
• 参考资料

想法

Web API这东西在工作中经常接触，但如果要自己说出相关的一些东西来，除了开发时对接接口的经验，就没有其它什么的了。目前为止接触的工作，主要是跟后台相关人员交流需要什么字段和格式，并没有比较系统的认识。看了《Web API的设计和开发》后，感觉到脑海里多了新的一块区域，也觉得对自己有用，在此做初步的梳理和整理。

什么是 Web API

书中Web API是指“使用HTTP协议通过网络调用的API”，API是“Application Programming Interface”的缩写，是软件组件的外部接口。Web API就是一个Web系统，通过访问URI可以与服务器完成信息交互，或者获得存放在服务器的数据信息等。这样调用者通过程序进行访问过后即可机械地使用这些数据。

平时经常听到的是URL，这里提到的URI跟URL又是什么关系呢？URI是Uniform Resource Identifier的缩写，中文就是统一资源标识符，它规定了一种句法结构把一个资源独一无二的标识出来。URL是Uniform Resource Locator
的缩写，中文就是统一资源定位符，它表示一个资源可以在那里找到。还有一个比较少见的URN，是Uniform Resource Name的缩写，用于在特定的命名空间资源的标识。用维基百科里面比较形象的解释就是：

URI可被视为定位符（URL），名称（URN）或两者兼备。统一资源名（URN）如同一个人的名称，而统一资源定位符（URL）代表一个人的住址。换言之，URN定义某事物的身份，而URL提供查找该事物的方法。

简单来说URI包含URL和URN，建议使用URI比较严谨。

说到“机械地”，这里是指Web API所使用的URI同人们使用浏览器直接访问的URI截然不同，Web API不是人们通过直接输入或点击链接来访问的，而是由程序进行调用，从而获取数据，并用作其它用途。

需要设计 API 的场景

下面是比较常见需要设计Web API的情况：

1.将已发布的Web在线服务的数据或功能通过API公开

这个是公开发布Web API最古老的动机之一，现在很多企业都提供这样的服务，比如Google提供检索的API。ProgrammableWeb是一个收集各类公开API信息并对外提供API目录检索功能的在线服务。

2.将附加在其它网页上的微件公开

例如想要使用某个平台的视频播放服务，按照说明文档引用公开的js即可。

3. 构建现代Web应用

这个就很常见，像各类电商网站，提供企业内部管理的一些网站都是这类。

4. 开发智能手机应用

涉及到服务器和客户端在网络上进行数据交互的，都需要设计API。

5. 开发社交游戏

社交游戏是多人参与相互互动进行的游戏，需要将玩家的相关游戏数据保存到服务器，同样是需要设计API

6. 公司内部多个系统的集成

现在，不少的公司都会将公司内部业务信息化，需要根据公司的内部需求来进行开发，不同时期搭建的信息系统、不同岗位搭建的信息系统杂乱无章同时存在的情况很多。这种情况下，如果各个系统进行集成，或各系统之间需要互相访问数据库，那么一处变更可能引起其它不良反映，风险也会不断增加。针对这种情况，通过Web API将个系统集成，就能将影响控制在最小范围内。

公开Web API的重要性

先看一下Web API的一些历史。Amazon（亚马逊）的Product Advertising API是从很早以前就广为人知并大获成功的Web API。该API于2003年对外开放，它能够同广告营销联盟结合，通过使用该API，任何人都可以简单的把Amazon上的商品通过自己的网站进行销售，从而将收益的一部分放入自己口袋。这样无论是企业还是个人开发者都可以获取利益，这种模式受到很大关注，并慢慢普及开来，最终使Amazon公司的收益大幅上升。

公司自身投入大笔资金建设的信息系统，收集了大量数据，而后将其免费对外公开，从短期来看似乎有损公司的利益，但是通过对那些有能力公开新系统、新服务的开发人员公开API，无疑会给公司原有的服务增加新的价值，使公司的核心服务获得更大的发展动力。国内的微信一些功能的迅速普及少不了广大开发者的参与。

所以那些对外提供Web在线服务但未公开Web API的，建议立刻行动起来对外公开Web API。

优美 Web API 的几个特性

Web API设计的不优美也是可以正常使用，那为什么要设计的优美呢？这个问题对于开发人员来说，就像是问为什么代码要写的优美，对于产品经理来说，为什么产品要优美，对于设计人员来说，为什么设计要优美。想必各自都有自己的答案。优美的Web API有如下几个特性：

• 易于使用
• 便于修改
• 健壮性好
• 不怕公之于众

如何设计开发 Web API

在设计、开发API时，首先需要决定的是将什么样的信息通过API公开，以及作为访问目标的端点（在Web API语境里，端点是指用于访问API的URI），再考虑交互方式与合适的响应数据格式，最后还需要考虑安全性以及访问控制等相关内容。

两个重要原则

书中的主要想包含2个重要原则，这2个原则感觉在其它方面也很有参考价值：

• 设计规范明确的内容必须遵守相关规范
• 没有设计规范的内容必须遵守相关事实标准

规范也是人定的，但这些规范并不是由某个人随意决定的，而是经过很多人评估、综合讨论各种不同观点后才决定的，因此遵循这样的规范合情合理。对于遵循规范设计出来的API，使用过其它API的开发人员会感到很熟悉，方便使用，减少开发耗费的精力。虽然不可否认一些规范实在没有美感，但这些也是曾经由某个人发明，逐渐演进而来，如果能为当前规范进一步演进创造契机，那可以说是相当杰出了。

一种设计规范能成为世界标准，应该有它的理由。不能仅以“规范就是这样的”、“其它地方就是这样做的”为由来进行API设计，而是要理解为什么会有这样的规范和事实，才能设计出更优美的API。

自己的一点思考

了解到这些基本的知识后，我就在想这个是在开发中的那一步，回想自己在接触新的业务开发过程中，大部分是后台决定了URI，也就是说并没有作为一个独立的环节讨论如何设计开发API，而是单方面的完成了大部分工作，这种情况也许因为这个只用在内部，并没有表明是要用来公开。

这个就表明了从一开始在公司内部，并没有一个相关的规范，表示那些API是需要公开，那些是不需要公开，也没有承接此前提的开发说明。如果说有其它独立的团队在完成这个任务，那就不太一样了，但目前为止没有碰到过。

现在自己大都是在已有的前提下接手开发，那么如果在一个全新的项目里面，这个又该是在那一步呢？个人认为在需求评审后就要开始进行相关的工作，这个相当于接口文档，但又有些不一样，因为并不是所有的API都需要公开，这个应该也是会给后期带来便利。

参考资料

• URL和URI的区别
• 标识互联网上的内容
• 统一资源标志符
• 《Web API的设计与开发》