最近对service的API设计，在team内有些讨论，主要集中在API是足够抽象、通用好呢， 还是具体、易用好？

其实这个是要折衷的，通用的好处是以后更改API的可能性小，但坏处是想要通用，里面的字段就不能定义太死，不定义死，极端的例子是全部用Name/Value Pair，最通用，但client面对这些NV，根本不知道怎么去设值，这样的API很明显是不友好，难用的，而一个好的API应该是自明的（self-documenting）的。 所以需要折衷。

关于API 通用性（Generic）和 自明性（self-documenting）讨论继续...

这个折衷要看应用场合，世界上最大的分布式系统是什么？对，是万维网，它的API是什么，对，HTTP。 万维网包罗万象，所以其API（HTTP）要绝对的通用，可扩展。怎样做到呢，没有任何限制（constraint）的东西，无疑是最*、最可扩展的，所以稍微知晓HTTP的同学，不难发现在HTTP里，除了消息头的元数据名如 HOST，Connection-type等是要遵循协议规范的（消息头也是可扩展的，用户可以自行添加头部元数据，通常以X-开头），对于消息体（Message Body）可以说是绝对的*，没有一丁点限制，你可以在里面放HTML，也可以是XML、JSON，
也可以是图像，二进制流，音频，视频，可以说是世界上最通用的API。

再看一个场合，公司A和公司B合作，A需要提供一组API给B公司条用，好吧，B公司，我们决定使用世界上最通用的API给你用，www.A.com/service4B，可是里面的request body要怎么写呢？像这样针对性不叫强的API，最好还是具体一点，这样client看到你的接口，就基本知道要怎么调用你的服务了, 比如对于查询合同的API，你就必须要在HTTP Body里写明:

<contract>

<contractId>123456</contractId>

</contract>

或者用REST的思想，URI为 www.A.com/service4B/contract/123456.   这样的API失去了通用性，但其专用性以及对特定环境下的约束，正是B公司我们想要的。

还有API也是一个不断演化的过程，所以不用太担心当前的API是不是扩展性太差，这也是Agile的思想，包括HTTP从1.0 到1.X 也是在不断的演化当中。

当然一个企业级API需要考虑的因素还很多，这里先开个头，后面会结合公司的CommerceOS （eBay next gen public API)，在详细讨论....

还有个原因就是，刚才看到一篇文章《管理企业级API的7个最佳实践》，觉得说的还是很在理，先copy在这里，后面有时间再整理一下。

1. API优先的设计方法

SOA最佳实践就是将API开发从后端应用中完全地分离出来。“与其在执行应用之后再创建API，倒不如先尽己所能提前创建好一个接口，然后再将其与后端逻辑相挂钩。这样一来，问题便可逐个击破，开发者也可以更专注于清晰明了的API执行过程，而API测试也会变得更加容易。”Shafii如此说道。

2. 选择一个稳定的API运行时

运行时的选择可以说是至关重要。因此，我们必须要注意一个企业级API从创建开始的所有需求，比如可扩展性、实用性、可靠性等。即使API没有进行修改，也应该能够在企业内部和云端顺利运行。这样一来，开发者便可以干很多事情，比如利用云来获取更多额外资源，或者在充分准备之后，实现企业模型到云模型的转移等。

3. 创建一个*服务存储库

另外一个关键点就是将API开放到一个*存储库中，以便于开发者和终端用户发现。

4. 通过版本、策略和契约来管理服务

对于任何操作系统或应用程序来说，API的版本控制都是必不可少的，其重要程度不亚于安全性和策略管理。

5. 提升和开放你的API

Shafii强烈建议为API创建一个社区平台，并为其提供信息和技术支持。

6. 通过度量、分析来监控和测量API使用情况

在商业活动中，评估力度越大，就越能有效追踪到API的运行过程和结果。不管是从潜在的技术层面还是商业层面，一定的度量标准都会帮助开发者更好地了解API的使用情况。

7. 重构API以提升API用户体验和效率

对于这最后一点，Shafii更是反复强调，一定要对API保持不断的更新。