下载掌阅APP，畅读海量书库
立即打开
API是Application Programming Interface的缩写，指一种计算机接口，由一组定义和协议组合而成，定义了多个软件系统之间的交互。通过API，设计者可以公开数据与应用程序功能，供开发人员与用户使用。API在互联网企业中大量应用，对于广告平台也非常重要，是广告投放的入口，可以为广告产品及合作伙伴各方增加新功能。
设计API并不容易，冗余、复杂的API可能会给技术支持团队带来繁重的工作，为广告主增加额外的成本，从而降低广告平台的竞争力。Programmable Web的创始人John Musser总结了API设计的5条基本原则，具体如下。
价值性：API必须为客户提供价值，例如客户利用API可以访问有价值的数据，实现有价值的功能，或者对目标用户进行认证与授权。
规划性：API需要针对企业的业务模型进行分析和抽象，从而形成整体一致的规划。
灵活性：API的设计需要简单、灵活、容易集成。
可管理性：API需要能够实现有效的管理与衡量。
可支持性：企业需要为API提供持续、高质量的开发者支持。
首先API必须具有价值。API的价值可以来源于多个方面，包括但不限于以下几点。
有价值的服务：API设计者可以将有价值的服务包装成API，例如Twilio公司将通信能力包装成API。
有价值的数据：企业可以将有价值的数据包装成API对外提供服务，例如，AccuWeather.com提供天气数据API。
有价值的用户认证：企业可以将用户认证包装成API对外提供服务，例如Twitter、Facebook、LinkedIn、腾讯、微博等将用户认证包装成API对外提供服务。
有价值的功能：企业可以将核心功能包装成API，例如人工智能公司将图像识别能力包装成API，提供对外服务，Salesforce公司将销售能力包装成API对外提供服务。
有价值的市场：例如Facebook、Google广告系统的API，对外提供它们的广告电子市场服务，广告主可以参与电子市场竞价排名。
任何公司只要能将API对接到现有产品并加以改进，几乎都可以通过API产生价值。如图2-6所示，API价值主张的发现是一个迭代过程。
1）描述用户需要完成的工作，例如：
在紧急情况下，通过各种通信通道（电话、邮箱、聊天工具）自动向团队成员发送告警；
对数据进行备份以确保万无一失；
对企业电子邮件进行检测以过滤垃圾邮件。
2）确定用户在完成工作中可能遇到的难题、痛点。
通过多次发送、检测故障、发送多条消息而不只是一条消息，根据用户位置与不同的消息传送系统集成，确保发送的可靠性。
确保安全传送文件，同时还要最大限度减小传输带宽。
接收与存储大量数据并尝试实时关联这些数据。
3）总结用户可能获得的潜在收益。
可以通过同样的机制（API）发送其他类型的通知，这些通知并非紧急情况下的告警，而可能是新的业务增长机会（如销售线索）。
图2-6 API价值主张的发现过程
如可靠性达到业务要求，则可以去除其他存储设备，降低系统复杂性。
根据事件自动触发操作。
通过不断重复和优化这一过程，最后可以提炼出API的价值主张。价值主张可以是一句话。例如对于消息发送这个API，价值主张可能为：
为开发者提供可靠的、无延迟的文本与富媒体消息传递功能，用于高度关键的业务应用；提供RESTful、GraphQL接口帮助开发者快速集成。
确定API价值主张之后，API设计者需要对API进行深入的思考与总体规划设计。刚开始可以围绕以下问题进行推导与考虑。
API需要达成什么目标，需要解决哪些用户痛点或者为用户创造什么收益？这个问题应该根据API与客户业务的关系，从API价值主张中确定的难点、痛点和收益，是否满足关键需求（是痛点还是收入机会），以及API能否为用户带来业务改进的衡量标准（速度、收入、成本节省、创新能力）等方面来回答。
API的使用者是什么样的人群，谁会使用API？这个问题应该从API设计者与API使用者之间的关系（API使用者是现有客户、合作伙伴还是外部开发人员）、API使用者的角色（API使用者是数据科学家、移动开发人员、后台开发人员还是运维工程师）这些方面来回答。
API支持哪些场景、哪些用例？借助API价值主张，发现API使用者的需求与痛点并提供解决方案，这也是API的商机所在。
如何随着时间的推移扩大使用者的价值主张？深入规划API价值主张，考虑内部与外部未来的变化以及可能的增长点在哪方面。
同时需要考虑到，API的设计、维护与优化会产生成本。这些成本可以通过API的价值来平衡，因此API设计者在API规划之初就需要明确业务模式。设计者可以思考以下要点：
自己所在企业的核心业务是什么？
如何使用API来加速企业的业务发展？
API设计者可以利用现有业务资产或者专业知识以新的方式来创造商机。在某些情况下，API也可以在企业现有业务模式之外产生全新的商机。结合业务模式思考与规划API对于设计有效的API非常重要，因为确定正确的业务模式具有以下好处。
凸显API对于企业的价值，从而推动API程序作出对客户的长期服务承诺。没有这种长期服务承诺，就不可能有资源来建立、运行、优化与维护API程序。
帮助定义产品的功能，从而更好地发掘与满足开发者的需求，完成API的价值性并持续推动API发展。
确保API设计考虑到企业内的角色与职责，例如企业的哪个部门维护API生成价值的哪些模块。这也倒推API价值主张的发现，确定API能为用户和API开发者带来哪些收益，以及如何在两者之间进行平衡（确定API涉及的利润中心与成本中心）。
在确定业务模式并开始API规划设计之后，设计者可能会遇到以下设计决策。
API需要支持什么协议（TCP、HTTP、SOAP、RESTful、GraphQL等）？
API需要提供哪种或哪些数据格式（XML、ProtocolBuf、JSON等）？
API的安全性该如何考量？
是否需要使用某个开源框架？
是否需要使用某种设计模式？
API是否需要支持旧版本？
这些设计决策在API投入使用之后通常就比较难变更，特别是对于已经向第三方开发者公开的API。设计决策的变更方式通常是发布新版本，而不是废弃旧版本，这时API设计者需要长期维护不同的API版本，带来较高的维护成本。
API的规划通常也涉及API团队的规划与组建。API团队与产品团队关系密切，与产品团队类似，API团队也非常多样化，但通常应该包括以产品为中心的战略目标负责人、以设计为中心的团队成员（确保最佳API设计实践）、将API技术落地实施的开发工程师、运行API服务的运维工程师。随着产品研发的进展，还需要逐步加入其他人员，如支持社区团队成员、API传播者、安全审查人员等。
好的API设计有一些核心原则，这些原则可能在实施上略有不同。可以做个类比，不同汽车厂商的汽车构造可能各有不同，但熟悉一款车型的司机可以在很短的时间内熟练驾驶另一辆车。这种标准化的API是API设计者追求的目标之一，经验丰富的开发者基本不需要说明就可以开始使用。
API的设计首先应该遵循简单性的原则，而简单性取决于使用场景。特定的设计对于一个使用场景很简单，对于另一个使用场景可能非常复杂，因此API设计者必须平衡API方法的粒度。API设计者可以从以下几个层面考虑简单性。
协议类型：API可使用的协议多种多样，其中RESTful相比SOAP更简洁（见图2-7）。较新的API设计越来越集中于RESTful、GraphQL这两种。
图2-7 SOAP、RESTful两种API对比
数据格式：API可使用的数据格式非常多，常用的有XML、JSON、Protocolbuf，其中JSON相比XML更紧凑（见图2-8）。JSON经常与RESTful协议搭配使用。
图2-8 XML、JSON格式对比
方法结构：应尽量设计通用的方法，返回广泛的数据。方法通常以特定的顺序调用以实现某些用例。
数据模型：API实际显示的数据模型应该与底层数据模型隔离，将底层数据模型通过API发布给使用者，会带来比较严重的可用性和可维护性方面的问题。
身份验证：不同的身份验证机制具有不同的优缺点，应根据具体使用场景选择适合的机制，不宜一刀切，一律采用过于严格的身份验证机制。
使用策略：开发人员的使用策略，例如权限与配额，应该清晰，易于使用。
一般来说，API的设计应越简单越好，但简化API可能会与API的灵活性原则相冲突。仅仅考虑简单性而创建的API可能存在过度定制的风险，即只为非常具体的用例提供服务，不适用于其他场景，失去灵活性。API设计者可以从以下方面考虑灵活性：
提供多种选项，如多种数据格式、协议、版本；
给开发者更多的控制权，例如提供分片查询与更新，提供批操作（如批量更新）；
提供高级选项，如钩子入口（webhooks）、流处理方式（streaming）、缓存选项（caching）；
找出操作空间中的原子操作，通过组合原子操作来覆盖整个操作空间；
确定常见和有价值的用例，设计第二层次的元操作，这些元操作通过组合多个原子操作来为常见和有价值的用例提供服务。
总之，要实现灵活性，需要设计者从底层系统和底层数据模型出发，发掘潜在的操作空间，定义这些操作中的哪些子集是可行且有价值的，从而在简单性和灵活性之间找到平衡。
API可以作为跨企业内部网与外部云，连接应用和数据的工具。API管理是指分发、控制、分析API的过程。如表2-2所示，可管理性包括管理与衡量两方面，它的目的是确保API团队与API使用者（开发人员）都能监控其API活动，满足API使用者或应用场景的需求。
表2-2 API的管理与衡量
API的版本管理方法有很多。通常应在API的初始版本中设定好版本管理方法，并在之后的实施过程中保持一致。表2-3给出了RESTful设计中的多种API版本管理方法。
表2-3 RESTful设计中的多种API版本管理方法
API的安全性包括安全协议与安全认证。越来越多基于HTTP的API将SSL作为唯一支持的协议，大多数API使用OAuth 2.0作为安全认证方式。OAuth是一个开放网络标准，其作用是让应用程序安全可控地获取用户的授权，与服务提供商（这里是API提供商）互动。API设计者也可以选用OpenID Connection来进行用户认证。
API设计者在设计API时就应制定全面的衡量指标，包括流量、开发者、服务、市场、技术支持、商业等维度（见表2-4）。这些被量化的指标驱动着API不断丰富与完善。
表2-4 API衡量维度与指标
API速率限制（rate limiting）是安全设计中非常重要的部分。DoS攻击就是服务器受到无限请求攻击导致过载的例子。速率限制还使得API可扩展。如果API在推出后大受欢迎，使得流量激增，可能导致严重的延迟，而增加速率限制可以较好地处理这种情况。速率限制可以应用于多个方面，例如限制每秒请求数（QPS）、每秒处理事务数（TPS）、每秒传输数据量或者同时建立的TCP连接数。API速率限制的最佳做法是提供免费访问层和付费访问层，每层对应不同的限制，对于付费访问层，可以通过各种因素将速率限制货币化。例如，AWS DynamoDB对于不同的QoS（服务质量）限制有不同的付费标准。此外，API设计者在设计API速率限制时还应考虑以下因素：
超过速率限制时是否应该限制请求？
超过速率限制后，新的请求或者调用是否会产生额外的费用？
超过速率限制后，新的请求或者调用是否会触发特定的错误码？如何定义该错误码？
例如，GitHub在文档（https://developer.github.com/v3/#rate-limiting）中说明了已验证与未验证请求的不同速率限制，并定义了返回的HTTP头以及某些速率限制命令的含义。该文档还说明了用户如何检查其当前使用速率，如何为特定应用程序设置速率限制，以及在客户端超过速率限制或者出现API滥用（例如调用API快速创建内容）之后可能遇到的限制。
API的可支持性体现在API团队对API用户需求的全方位满足。满足API的用户需求有两个基本原则：一是API应该设计一种产品或服务，二是产品要易于访问。
API设计者可以通过优化TTFHW（Time To First “Hello World”，首次问世时间）这一指标来改进API的可支持性。换言之，要缩短开发人员使用该API创造MVP（最小可行产品）的时间。优化这一指标时要从开发人员的角度来考虑API的易用性，而开发人员也可能在多个同类API中寻找可以让工作最为有效的那个API。对于开发人员而言，TTFHW也是辅助决策的关键指标。
定义TTFHW指标的开始与结束时，建议尽可能覆盖API使用者即开发人员参与的全流程，然后优化这一流程，使其尽可能快捷、方便。能够快速完成整个过程还可以使开发人员确信API组织良好，使用API组建的系统可以快速正常工作，而将“成功时刻”延迟太久可能有失去API用户的风险。
API设计者可以考虑从以下方向优化TTFHW指标。
明确API的目标。如图2-9所示，Twilio明确API的目标为云端语音通信API，这个过程分为三步：用户呼叫企业电话号码，Twilio收到电话呼叫，Twilio通过API回调开发者。这三步清晰地向API使用者传递了API的目标。通过定义清晰的目标，API为开发人员提供明确的价值，助其应对显而易见的难题或把握商机。这里的价值包括多个方面，例如提高安装覆盖率的方式，提升品牌知名度，提升盈利水平等。
提供免费的API体验或评估版本。要求付费可能会显著增加TTFHW，因此大部分成熟的API产品会提供一个免费的体验或评估版本。
提供快速自动注册页面（如通过手机号码和验证码登录），或者允许在不注册的情况下体验大部分功能。
提供结构合理、内容准确的文档。
提供丰富的代码范例，覆盖各种API使用场景。
提供调试工具，辅助API使用者调试和使用API的代码。
建设API支持社区，例如可以通过论坛、博客、社交媒体、邮件等方式，建立和丰富API开发者社区。
建立API布道师团队，通过组织活动、参与会议、开发者互动等方式宣传与推广API。
建立API生态，通过生态系统中的合作伙伴加速API的推广与应用。API团队可以作为API提供商在合作伙伴与供应商的生态系统中运营，这些合作伙伴通常拥有自己的内容分发渠道。建立一个API互补联盟有助于提高API的采用率。
图2-9 Twilio voice API使用说明
除了TTFHW外，还推荐API设计者关注TTFPA（Time To First Profitable App，首次盈利应用时间）。TTFPA比TTFHW更难定义，因为对盈利的定义取决于业务战略。考量TTFPA的意义在于它会使API设计者将与API相关的操作作为API的一部分，并持续迭代。
API团队可以通过以下问题来评估用户体验是否合理。
如何在5分钟内解释API的价值？最适合开发人员的API价值主张的“电梯行销”是什么？
API对应的TTFHW和TTFPA指标怎么定义？如何优化？通过考虑端到端的TTFHW来提高对API使用者的友好性是十分有效的方法。在可能影响用户体验的元素（如网站、文档）发生变更或者API本身发生变更时，需要仔细评估它对TTFHW与TTFPA的影响。
API的注册、登录流程如何？是否做到了尽可能精简？这一流程应该与API的代码用例保持一致，可以分为简单部分和高级部分：简单部分应尽可能简单直观（例如不需要登录也可以访问），以降低早期开发人员的使用门槛（降低TTFHW）；对于高级部分的用例，如需要访问敏感数据，则可以要求更高级别的安全认证。
API是否保持足够灵活，是否对开发人员具有长期吸引力？API保持足够灵活可以吸引尽可能多的开发人员。例如，同时提供多种语言（C++、Java、Python等）的版本，可以吸引使用这些语言的开发人员。留住开发人员并帮助他们取得成功也能提升口碑，从而带来更多的开发人员。
当开发人员遇到问题和困难而寻求技术支持时，支持流程是怎样的？支持可以分为两个层次：对于简单的问题，提供自助服务方法，好的文档、常见问题解答或者友好活跃的论坛能解决开发人员遇到的大部分问题；对于较深入的问题，可以通过邮件、电话等方式，由API团队支持工程师提供支持。
API文档是否有助于开发人员创新？API文档是否覆盖了各个技术细节？当开发人员需要进行创新，或者实现超过API代码用例提供的功能时，他是否能从文档中受到启发？
API可以将企业的各种数据、应用与设备联动起来，使各项技术能更好地相互通信并协同工作。同时API也被认为是下一代业务开发的基石，是Web站点的核心内容，可以将数据、资源与服务以安全的方式提供给外部开发者访问。
本节介绍了API设计的5条基本原则。设计一个好的API是一个艰难、持久的过程，设计一个差的API则很容易。导致差的API设计的十大原因如下：
缺乏完善合理的文档；
缺乏技术支持；
过于乐观的假设前提，假定设计与实现了API，开发者自然就会到来；
期望一个框架（如MVC框架）能够提供出色的API；
糟糕的用户体验；
临时的、仓促的、没有预先告知的版本发布；
复杂的安全性设计；
API公开了底层数据模型；
使用了RESTful风格的API设计，但忽略了HTTP规范；
糟糕的异常处理。