ASP.NET Web API实践系列11,如何设计出优秀的API

本篇摘自：InfoQ的微信公众号

在设计API的时候考虑的问题包括：API所使用的传输协议、支持的消息格式、接口的控制、名称、关联、次序，等等。我们很难始终作出正确的决策，很可能是在多次犯错之后，并从中吸取经验，才能够接近正确的决策。而通过迭代的方式，只要有足够的机会，就能在API设计方面接近完美。

一个公开的API就像砖石，它是永恒不变的。（引自Joshua Block）

要知道，API的变更代价很大，并且伴随着很大的风险。但同时，破坏性的变更通常不可避免。

我们要做的是：在接口发布之前尽早迭代修复问题。也就是说，我们先设计与实现接口而不发布他们，等进行足够的审查与测试再发布。

具体来说，可以按照"草图设计→原型设计→实现"的方式去做。

草图设计

草图无需反映出整个接口，无需过于深入。API草图设计过程有一种好方法，就是定义接口中最明显的单词列表。有哪些单词是用户必须知道的？哪些单词能够最好地表达目标受众的目的与任务？通过回答这些问题，创建一份接口的词汇表。

原型设计

这个阶段对草图阶段的一些假设进行验证。一个好的原型大致是：

● 可以被调用
● 能够处理真实的请求信息
● 在必要的时候提供响应
● 开发者能够通过原型API创建出一个简单的应用

如何保证创建原型的成本低于一个完整的实现呢？

--模拟响应的消息，不是由后台系统输出响应信息，而是模拟响应信息，这种方式也称为接口的虚构(mocking)。

建立原型的目的是什么？

--为投入找到一个合适的范围，能够至此后续的迭代。

通过原型，有机会获得用户反馈，更接近最终的实现。

实现

实现是将一个原型接口转变成实际可以使用的接口。

API设计的自动化工具

● 适用于原型设计的工具：Swagger,RAML,Blueprint,WADL。
● 适用于草图设计的工具：Rapido!