别再设计易碎的Web API

原文作者Mathieu Fenniak在博文中大呼：不要再设计易碎的Web API 了，否则你的合作伙伴或第三方开发者会因此恨你，而离你远去的。他认为，想设计出相对稳定、牢固的API，关键在于以应用目的为中心。文中还分享了设计优秀API需要注意的几点事项，我们一起来看下：

如果破坏了API，客户会因此而恨你

很多Web API发布后，它就像被牢牢刻在石头上无法做出兼容改变，这是个可怕的现象。倘若你破坏了API，你的客户会因此而恨你，紧接着就是你的老板。因此，你必须对该API进行更新、维护。

如果API设计的很好，那么它不会这么脆弱

减少其脆弱性或增加其韧性是管理API设计的方式之一，其关键在于以应用目的为中心做设计。也就是SOA领域，所谓的面向业务（business-orientation）。也许这个概念很难理解，下面的这个示例能很好的说明这一点：

URL之间的区别是什么呢？

http://api.fbi.gov/wanted?order_by=notoriety,desc&limit=10&page=1&fields=name,aka,known_associates,reward,description,last_seen

这是一份来自美国联邦调查局的列表。该API包含了许多功能：你可以预定任何领域，按照升序或者降序进行排列；可以指定结果计数 ；可按页查询并且还根据指定详细信息进行检索。

对比看下这个URL：

http://api.fbi.gov/wanted/most

两个URL虽然有着相同的目标，但是执行方式不一样。第一个是名程序员设计的，他能提供任何你想要的功能。设计中没有描述用户的意图，但却利用请求定义详细信息来替代。

第二个URL意图则非常明显，显示联邦调查局头号通缉犯名单，模糊的细节，这是根据意图来进行设计的。

根据”意图“设计API，减少其脆弱性，有哪些优势呢？

1. 易使用——没有复杂的程序、复杂的细节，易于学习；
2. 灵活性——意向驱动API可随着服务器端的变化而变化；
3. 一致性——一致性是API设计必备的一大特性；
4. 松耦合——这是向后兼容性问题。你只需返回一个固定的值，后端兼容在意向驱动API中会运行的很好；
5. 可优化——当对数据库进行更新时，可计算优化而不是在内置的需求上，这比优化每个组合的程序设计要困难得多；
6. 可缓存——易缓存。程序员的设计使得缓存困难（正常可查询参数）和无效（比如限制=5 / 10 / 15缓存未被命中）；
7. 易开发—— 由于高复杂性使得开发和测试测试程序员的 API变得更加困难和耗时。
8. 高效验证模型缓存 — — 快速检查 If-None-Match/If-Modified-Since HTTP标头并作出"304 Not Modified"响应。

但是，我需要一个更加通用的API设计……

为什么需要通用的API设计？这是因为意向会让你设计出更好的API。比如，API的灵活性。灵活的API非常有助于于开发用户界面，允许按字段排序、可自定义分页、 排序和筛选或搜索。

此外，铭记UI意图，还可以提供一个易于使用、开发、灵活、一致、松耦合、可优化、可缓存和高效的API的设计决策。

DRY原则（Don’t repeat yourself）

在执行过程中不要使用重复原则，但在API设计中无须担心重复设计。如果你提供了多个API端点可根据不同意向来检索相似的对象，从常见的代码路径开始吧。 为用户提供更多具体的服务，你需要不断对API进行维护。

这个真的适用于现实的API领域吗？

这是GitHub提交的一份Status API示例，通过持续集成服务来标记存储库版本。

1. 定义特定的功能：指定一个国家修订的版本库
2. GitHub会自动将请求相关联的，显示在一起
3. 无HTML 或可自定义的国家 ；API 有极少数量的数据需求。
4. 面向未来： 它以简约的方式满足定义的问题。
5. 状态相关修订 ；提交添加更多的请求工作。
6. GitHub 具有灵活性，可以进行更改，而不会破坏兼容性：1. 对于API，GitHub暂不支持重写功能整个请求功能；2.可适用于其他UI领域；3. 如果 GitHub变成MercurialHub、SubversionHub、PerforceHub、 CvsHub、RcsHub，API可同样被应用。
7. GitHub灵活显示提交状态： 可在移动应用中显示状态、本地化的文本易合并。

还有个真实的例子 Twilio’s AvailablePhoneNumbers API，目的是为了搜索电话号码分配到您的账户中，这个看起来就像典型的API集合，但是细节和意图关联并不大。

总结：

综上所述，不再设计脆弱的Web API，我们得出几点：1.根据自己的意向设计API；2. 在细节上是模糊的；3.提供多个API以区分用户意向；4. 通过分享常见的实现方式而不是提供一个通用的服务来减少代码重复。

英文出自： Mathieu.Fenniak