Web API 设计摘要

最近读了一本微电子书 Brian Mulloy 所著《Web API Design》感觉颇多收获，特对其内容做了个整理摘要以便回顾其观点精华以指导日常工作中的设计思路。

本文主要讲述 Web API 设计，追求一种更务实的 REST 风格。 正如作者所说 REST 是一种架构风格，而非严格的标准，没必要在形式定义上去做过多真论，到底什么才是真正的 REST？ 设计的目的是为了表达某样东西是如何使用的，那么 API 设计的成功与否是由开发人员是否能够快速上手并用的愉快。

下面讲述了 Web API 设计的 13 个要点。

本条是关于 URL 设计的，使用名词而非动词，让 URL 保持简单和符合直觉。
这条是针对资源型 URL 设计而言，为什么？请看下一条。

用名词表达来领域概念，可以极大的减少 URL（API）的需求量。
使用 HTTP 协议方法动作来操作领域概念集。
通过分离概念和行为极大简化了 API 设计，让 URL 中只体现概念而非行为。

/elements/elementId 的二级 URL 形式，第一级表达元素集合，第二级表达集合中某个具体元素 id，因此使用名词复数是作者推荐的更符合认知直觉的方法。 同时对于元素集合使用更具体的领域名词含义更清晰，若使用抽象的概念名词则表达不清。

为了表达对象间的关联性，有一种方法是体现在 URL 的层级中，但 URL 层级过深并不便于记忆和认知。 这里推荐用 HTTP '?' 后可选参数来表达关联条件，简化 URL 复杂性。

如果可能使用 HTTP 的错误码来映射 API 错误。 HTTP 本身已经定义了广为认知的错误码区间，按类型将错误映射到对应区间对开发人员的学习和认知更友好。 提供尽可能详尽的错误信息。

绝不发布一个不带版本号的 API。关于这点做过软件维护的都明白，有一点细节就是版本号的选择，请使用 v1, v2 整数版本号而非 v1.1 v1.2 这种带小数点版本号机制。这里有个心理认知原因，带小数点的版本通常给人的感觉会频繁变化，而对于一个开放的 API 而言频繁变更绝对是应该避免的，因此不要使用带小数点版本号机制。

当我请求某个对象时不需要其全部属性或需要分页时怎么办？上图中例子已经很好的回答了。

该条针对非资源型 URL 设计而言，因为有些情况就是请求做一个计算，如上图中所示请求金额按币种进行转换。 对于此类 API，使用动词就是合适的，但最好在你的 API 文档中将此类 API 独立分类说明。

开发人员对文件系统的后缀名命名方式都很熟悉了，因此使用后缀名表达响应格式是自然的。 那么默认格式应该选择什么呢？毫无疑问是 JSON，这一点与 javascript 是 Web 端的通用语言有关。

如上，既然我们要照顾 javascript 语言，那么属性命名自然也要采用 javascript 语言传统的驼峰命名法。

简单的搜索可以用资源型 API 来模式化，但全局的搜索 Google 模式大家都很熟悉。

为 API 申请独立的子域名，有且仅有一个是最好的，而且最好是这个域名模式 api.youdomain.com




有了 API 还不够，辅助以 SDK 工具包可以进一步减轻 API 使用者的负担，最重要的是还能避免 API 的误用和低效使用。 其实这里还有一个好处：

Eating your own dog food