今天，我们几乎可以在任何地方看到网络服务和API（应用程序编程接口），但更令人困扰的是，许多 API 的使用体验并不理想。你是否曾经体验过一个网络服务的API，并想，“他们的设计逻辑到底是怎样的？”我们相信许多人都有过类似的困扰。无论是因为设计欠佳、缺乏文档、频繁的改动，亦或是bug，使用API似乎总是暗藏挑战。

然而，这不应成为理所当然的情况。实际上，我们完全有能力设计出卓越的网络API，让开发者不仅愿意使用，我们自己在开发过程中也能乐在其中。那么，良好的 API 应该如何设计呢？这篇文章将分享一些宝贵的建议，帮助我们创建一款易于使用、文档清晰、设计优雅的API。

然而在开始之前，我们需要对 API 设计的意义有所了解。

API 在公司的业务中起着关键性的作用。对于开发者来说，使用 API 并非随性之举，他们需要投入时间和金钱去集成它、编码它并了解它。然而，API 带来的挑战同样不小，如果弃用某个 API，可能会带来巨额的成本。这恰恰体现了API在业务中的重要性。

设计良好的公开 API 可以吸引和留住用户。然而，糟糕的 API 设计可以快速引发问题，比如因 API 功能不完备导致大量技术支持电话的涌入。这可能会导致公司最有价值的数字资产变成了棘手的问题。

因此我们需要在设计 API 时格外谨慎和精准。我们的目标是打造出更多利多于弊端的API。

在我们构建产品时，我们通常考虑的是没有太多技术专业知识的普通人，我们会为他们创造一个用户友善的界面，同时还会获取他们的需求反馈。但在设计API时，情况变得有些不同。我们的对象是熟练的开发人员，他们会对每一个微小的问题进行细致的把握，并进行批判。这一点，我们必须要认识到。

作为 API 的设计者，我们视角与用户有微妙的差异。我们关注的是，API 应该怎样执行任务或提供服务。而用户，更在乎如何以最低的成本，轻松地获得他们所需要的东西。这种视角差异会引发问题，关键在于调整我们的视角，与用户的视角对齐。这看起来似乎明了无比，但实际上，很少有API真正将用户置于中心。

优秀的API具有一些特性，这些特性有助于提高API的有效性、可用性和成功性。

至此，我们对于什么样的API才能算优秀有了一些认识，下面我们就进入到优秀API的设计建议。

设计优秀 API 的第一步是从用户那里收集需求。在交谈过程中，要保持怀疑的态度。用户往往会提出具体的解决方案，而往往忽视了自己真正的需求。

我们的任务是引导用户介绍他们的核心使用情景，即使这在初看起来不太明显。在初始建议的“解决方案”下面，可能就隐藏着更好的设计思路。

此外，我们可能会期望设计出一款功能全面的 API，以解决各种各样的挑战。但我们必须首先全身心地专注于用户的实际需求。

我们才开始设计过程时，首先草拟一个高级的功能规格。这个早期的实验阶段，追求的是速度和灵活性，而不是详尽无遗的细节。

我们需要广泛地分享草案，既包括目标用户，也包括其他利益相关者。我们需要倾听反馈，因为其中很可能会有关于如何塑造产品的有价值的见解。

最关键的是，在初期不要做出过多的假设。需求收集阶段为后续工作打下了基础，在继续进行正式API设计之前，需花时间来做好这个环节。

设计优秀API的一条核心规则是，每一种API都应该专注于解决一个主要问题，而不是试图解决众多不同的问题。

尝试覆盖多种用例的“瑞士军刀式”API通常会失败，因为其覆盖范围过于分散，亦无法针对具体的用户需求进行优化。试图满足所有人的需求，往往只会导致功能体验的浅显。

相反，我们在建立每一个API时，都应确保保持明确且专注的目标。所有的能力都应直接满足那种特定的用户需求。任何与此无关的功能都应该被剔除。

例如，一款专注于地址验证的API有一个明确的用途。而专注于信用卡交易的API，虽然定义了不同的功能，但其依然同样保持了窄化的特性。

明晰和一致性是优秀API的标志之一。当我们在设计 API 时，清晰和一致的特性正是从我们为端点和资源选择的名称开始的。采用并一致应用命名规则，使得开发者可以直观地理解 API，就像他们在使用一种共通的语言。例如，遵循 REST 规范，将端点命名为 "/users" 以检索用户信息，这符合业界标准，可以帮助开发者不借助过多文档的情况下，理解端点的用途。

良好的 API 设计，需要充分理解和尊重用户的需求，并以此为指导，打造出易用、清晰且稳健的接口，只有真正将用户的需求放在心上，我们的 API 才能得到用户的认可，并让他们在使用中拥有舒适的体验。