How to Design a Good API?如何设计一个好的API？

We can find web services and APIs (Application Programming Interfaces) everywhere, but many are painful to use. Have you ever connected a web service using its API and wondered, "What were they thinking?" We have, and connecting services via API can be confusing. Whether due to bad design, missing docs, constant changes, or bugs, using APIs is often a struggle.
我们随处都可以找到 Web 服务和 API（应用程序编程接口），但很多使用起来都很痛苦。您是否曾经使用 API 连接 Web 服务并想知道“他们在想什么？”我们有，并且通过 API 连接服务可能会令人困惑。无论是由于糟糕的设计、缺少文档、不断的更改还是错误，使用 API 往往都是一件困难的事情。

But it doesn't have to be that way. We can create fantastic web APIs that people love using, and we'll enjoy making them too. So, what's the key to designing a good API? This issue shares the secrets, guiding us in creating a clean, well-documented API that is easy to use.
但事实并非一定如此。我们可以创建人们喜欢使用的出色的 Web API，我们也会喜欢制作它们。那么，设计一个好的API的关键是什么？本期分享这些秘密，指导我们创建一个干净、文档齐全、易于使用的 API。

Get ready, and let’s understand how to design an API that people enjoy using.
做好准备，让我们了解如何设计人们喜欢使用的 API。

---

The Importance of Good API Design
良好 API 设计的重要性

APIs are crucial assets for companies. Customers don't casually use APIs – they invest time and money in integrating, coding, and learning about them. However, relying so heavily on APIs comes with challenges. The cost of discontinuing an API's use can be substantial, showing the critical role APIs play in operations.
API 是公司的重要资产。客户不会随意使用 API，他们会投入时间和金钱来集成、编码和了解 API。然而，如此严重依赖 API 也带来了挑战。停止使用 API 的成本可能会很高，这表明 API 在操作中发挥着关键作用。

Well-designed public APIs have great potential to attract and retain users. However, poor API design can quickly cause problems - like floods of support calls from a dysfunctional API. This can turn a company's greatest digital assets into headaches.
设计良好的公共 API 具有吸引和留住用户的巨大潜力。然而，糟糕的 API 设计很快就会导致问题，例如来自功能失调的 API 的大量支持呼叫。这可能会让公司最重要的数字资产变得令人头疼。

This dual nature of APIs points to the importance of care and precision when designing them. The goal is to craft APIs that provide more benefits than drawbacks.
API 的这种双重性质表明了设计时谨慎和精确的重要性。我们的目标是打造利大于弊的 API。

When we build products, we're usually thinking about regular people without much tech expertise. We create a friendly interface, getting input on what they want. But API development is different - we're making an interface for skilled programmers. They notice even minor issues and can be as critical as we would be.
当我们构建产品时，我们通常会考虑没有太多技术专业知识的普通人。我们创建了一个友好的界面，获取他们想要的信息。但 API 开发不同 - 我们正在为熟练的程序员制作界面。他们甚至会注意到一些小问题，并且会像我们一样挑剔。

Our perspective as API designers is a bit distinct from that of users. We focus on what an API should do or offer. Meanwhile, users care about easily getting what they need with the least effort. These differing viewpoints cause problems. The key is shifting our viewpoint to match that of the user. Seems obvious, but few APIs take this user-centric approach.
作为 API 设计者，我们的观点与用户的观点有些不同。我们关注 API 应该做什么或提供什么。同时，用户关心的是用最少的努力轻松获得他们需要的东西。这些不同的观点会导致问题。关键是改变我们的观点以适应用户的观点。似乎很明显，但很少有 API 采用这种以用户为中心的方法。

Characteristics of a Good API
良好 API 的特征

A quality API has several characteristics that contribute to its effectiveness, usability, and long-term success:
优质 API 具有几个有助于其有效性、可用性和长期成功的特征：

Now that we've covered what makes a good API, let's move on to tips for designing one.
现在我们已经介绍了优秀 API 的构成要素，接下来让我们继续讨论设计 API 的技巧。

Requirements Gathering 需求收集

The first vital step for designing a quality API is gathering requirements from users. Approach this process with skepticism. Users often suggest specific solutions rather than focus on their underlying needs.
设计高质量 API 的第一个重要步骤是收集用户的需求。以怀疑的态度对待这个过程。用户经常提出具体的解决方案，而不是关注他们的潜在需求。

Our job is to have users walk us through core use cases to uncover those fundamental needs, even when hidden at first glance. There may be better design ideas lurking beneath the initial “solutions” suggested.
我们的工作是让用户引导我们完成核心用例，以发现这些基本需求，即使乍一看是隐藏的。在最初提出的“解决方案”之下可能潜藏着更好的设计理念。

Additionally, it’s exciting to envision very versatile APIs that address a wide variety of challenges. But we must stay laser-focused on users' actual requirements first.
此外，令人兴奋的是设想能够解决各种挑战的多功能 API。但我们必须首先关注用户的实际需求。

Start the design process by drafting a high-level functional specification. Speed and flexibility are more important than comprehensive details at this early experimental stage.
通过起草高级功能规范来开始设计过程。在这个早期实验阶段，速度和灵活性比全面的细节更重要。

Share the draft widely, both with target users and other stakeholders. Listen intently to feedback, as there will likely be valuable insights on how to shape a refined offering.
与目标用户和其他利益相关者广泛共享草案。专心倾听反馈，因为可能会有关于如何打造精致产品的宝贵见解。

The key is not making too many assumptions early on. Requirements gathering sets the foundation - take time to get it right before moving on to formal API design.
关键是不要在一开始就做出太多假设。需求收集奠定了基础——在进行正式的 API 设计之前，需要花时间将其做好。

One API, One Purpose 一个 API，一个目的

A key rule for designing excellent APIs is that each should focus squarely on solving one primary problem very well rather than trying to address too many diverse issues.
设计优秀 API 的一条关键规则是，每个 API 都应该专注于很好地解决一个主要问题，而不是试图解决太多不同的问题。

Creating a general “Swiss army knife” API attempting to cover many use cases often fails. The scope gets too scattered without a crisp, singular purpose tied to specific user needs. Trying to be everything for everyone results in shallow functionality.
创建一个通用的“瑞士军刀”API 试图涵盖许多用例通常会失败。范围过于分散，没有与特定用户需求相关的清晰、单一的目的。试图为每个人提供一切会导致功能浅薄。

Instead, limit the scope of each API we build. Ensure the purpose stays clear and focused. Align all capabilities directly to that goal of fulfilling a distinct user need. Anything peripheral should be removed.
相反，限制我们构建的每个 API 的范围。确保目标清晰、重点突出。将所有功能直接与满足独特用户需求的目标保持一致。任何外围设备都应该被移除。

For example, an API focused solely on address validation has a clear purpose. One centered exclusively on credit card transactions defines different but still narrow functionality.
例如，仅专注于地址验证的 API 具有明确的目的。专门针对信用卡交易的一种定义了不同但仍然狭窄的功能。

Clarity and Consistency 清晰度和一致性

Let’s explore some effective naming practices and standardized responses that contribute to an API's overall clarity and consistency.
让我们探索一些有助于 API 整体清晰度和一致性的有效命名实践和标准化响应。

Choosing intuitive names 选择直观的名称

When designing a good API, clarity starts with the names we choose for endpoints and resources. Adopting and applying naming conventions consistently allows developers to intuitively understand the API, like speaking a common language. For instance, using the RESTful convention for endpoints like "/users" to retrieve user information aligns with industry standards. This helps developers grasp the purpose of endpoints without excessive documentation.
在设计一个好的 API 时，清晰度首先从我们为端点和资源选择的名称开始。一致地采用和应用命名约定可以让开发人员直观地理解 API，就像说通用语言一样。例如，使用“/users”等端点的 RESTful 约定来检索用户信息符合行业标准。这有助于开发人员掌握端点的用途，而无需过多的文档。