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