【翻译】有效的对外API应用程序设计：保持用户回头率的5条原则

我们在开发API应用程序的时候，很容易迷失在主观的想法和决策中，并失去对目标用户的关注。可能你会觉得这个编程语言最简洁，那个框架最有效，但是这些并不是我们必须考虑的唯一方面。
只有当用户可以通过我们定义的接口轻松访问它时，我们的应用程序才是实用的。这需要有效的API设计。在本文中，我们将研究有效API设计的五个最重要的原则：独立性，简单性，一致性，错误处理和版本控制。

在设计我们的API时，我们必须考虑用户端会发现哪些有用的东西。这些方面中的某些方面特定于特定领域（例如使用熟悉的术语），而其他方面则是通用的。
最重要的五项原则是：
*** 语言独立性 –让用户选择编程语言

• 简单性 –数据的最小表示
• 一致性 –统一表示数据
• 错误处理 –发生错误时的简明通知
• 版本控制 –在不破坏现有用户端的情况下添加或删除功能**

有效的API设计还有许多其他原则，但是这五个原则是创建用户喜欢使用的API应用程序的基础。为了使我们的API有用，我们必须尽可能接触广泛的受众。

语言独立性

我们都有我们最喜欢的语言和技术，但是将这些选择强加给我们的用户会限制我们API的采用性。例如，如果我们选择创建Java Messaging Service（JMS）API，那么我们正在鼓励用户使用兼容Java EE的实现来使用该API。

相反，我们应始终选择尽可能与语言无关的选项。在当前的软件环境中，这意味着倾向于选择诸如REST API（最好使用JSON请求和响应主体），高级消息队列协议（AMQP）甚至协议缓冲区（protobuf）之类的选择。这些选项中的每一个都有许多流行语言的实现，包括Java，Python和Ruby。通过从API设计中抽象编程语言，我们允许用户选择最适合其需求的编程语言。这种灵活性意味着更多的用户可以采用和利用我们的API。

简单性

简单性有两个主要好处：一个对我们有益，另一个对我们用户有益。给我们带来的好处是，简单的API通常意味着我们所需的工作更少–更少的代码，更少的测试，更少的错误余地，更少的开发时间和更少的重复。对我们的用户来说，好处是使用我们的API的代码可以更简单-甚至可能更小。与我们的代码类似，使用我们的API所需的代码与我们的API的复杂度成比例增长（更不用说用户端的其他测试和存根了）。

为确保我们的API开发过程尽可能简单，我们应遵循一些基本规则：
除非有非常有 说服力的理由，否则请采用两种设计中的较简单的一种。
尽可能使用原语（例如字符串和数字）作为值，并仅在必要时引入新的数据结构。
仅包含所需的信息（即，遵循YAGNI原则）-将来的证明会导致需要维护更多的代码并使用
更大的API。

一致性

当用户使用我们的API（尤其是那些经常使用它的API）时，他们将开始遵循我们的约定，并期望在整个API中使用它们。
最佳选择取决于API本身的上下文和性质，但是无论我们选择哪种方式，我们都应该坚持并始终如一地使用它。保持一致可以获得一些重要的好处：
用户知道，通用表示意味着资源在任何使用位置都具有相同的含义。
用户可以创建通用代码来处理通用表示。
用户可以快速了解任何出现在其上的资源，因为他们之前已经看过它。
有时候，我们必须打破常规并使用不同的表示形式，但应将这些情况限制在我们有充分而令人信服的理由时。

错误报告

尽管我们希望我们的应用程序一直都能按预期运行，但是在实际应用程序中，这并非总是可能的。失败既可能出现在用户发送给我们的请求中，也可能出现在我们生成的响应中。例如，我们的API可能被设计为查找与注册用户关联的地址，但是如果没有与提供的用户ID关联的用户，则我们的API必须发出错误报告。

版本控制

有效的API设计最容易被忽视的方面之一就是版本控制。对于大多数项目，很难知道我们的API将从现在开始六个月，一年甚至五年的位置，但是为将来做准备很重要。最终，我们的API将会发展，我们将添加新功能并删除不需要的功能，但是我们不能破坏现有的用户端。如果用户端期望资源可用或消息具有特定格式，则更改这些现有期望（尤其是先不弃用它们并给用户端腾出时间来适应它们）将使API设计不佳。

相反，我们需要对API进行版本控制。对于REST API，我们可以v1在URL中包含一些版本字符串（例如）：

/api/v1/foo/bar

这样/api/v1，即使版本2发行了，用户端也可以继续调用，以确保用户依赖的API保持稳定。对于基于消息的API，这可能意味着要包括一个版本标头，以将消息的一个版本与另一个版本区分开。

无论我们选择哪种机制，规划未来并考虑用户的稳定性都是很重要的。每次我们发布新版本的API时，这种简单的添加将对保持用户很长的时间并减少他们的焦虑有很大帮助。

结论

有效地解决用户问题的API包含无数的小细节。仅此一点就可以使我们陷入追求完美API设计的困境。相反，我们应该关注有效API设计的最重要原则-即语言独立性，简单性，一致性，错误处理和版本控制。尽管不够全面，但仅这些一项就可以极大地改善我们的API设计，并使我们的API易于使用。
翻译及演示工具：Eolinker——www.eolinker.com