什么才是“好的”API？这是许多开发人员在设计他们的第一个 API 时会问的问题。虽然网上有数百种资源，但对于什么是“好”的定义各不相同，但其中大多数都有一些相似的主题。逻辑端点命名约定、清晰的错误消息、可访问性和可预测性都是任何精心设计的 API 中的关键部分。最重要的是，我曾经使用过的每一个好的 API 都有清晰易懂的书面文档。另一方面，糟糕的文档是我使用任何 API 时最大的挫败感之一。 Stripe 是具有优秀文档的优秀 API 的一个很好的例子。任何使用过它的开发人员都可以证明它写得有多好。凭借明确定义的端点、透明的错误消息、可用的示例、大量出色的 SDK 和符合标准的方法，Stripe 经常被用作 API 开发的参考点。甚至他们的文档也被用作许多免费和商业网站模板的灵感来源。
在设计 API 时，通常希望采用“先构建”的方法，尤其是在利用现有产品的架构时。不幸的是，这种思维方式并不遵循我们在构建具有图形界面的应用程序时遵循的标准可用性实践。我们采用以用户为中心的 API 设计方法非常重要，因为我们正在开发供其他开发人员使用的产品。如果我们不能同情他们的需要和挫折，那么我们还能同情谁呢？这种以用户为中心的关注点是开始编写 API 文档而不是仅仅设计它的重要原因。当您创建好的文档时，好的设计就会随之而来，但反之则不一定正确。
当您使用预先存在的架构时，在编写任何代码之前设计 API 可能会很困难。您对系统如何工作的先入为主的观念会影响您的设计，并可能导致 API 不合逻辑。首先从文档开始将迫使您设计一个不拘一格的 API。如果您编写的文档是您作为用户想要阅读的，那么您自己的用户很可能也会欣赏它。
几乎与文档内容一样重要的是它的易读性。有大量的服务可以让这一切变得异常简单，甚至可以生成动态文档和漂亮的模板。一个很好的起点是一个名为 API Blueprint 的开源 API 文档库。 API Blueprint 允许您使用 markdown 构建 API 文档，并将其导出到结构良好的 JSON 文件中，以便导入到许多服务中。 Apiary 和 Gelato.io 这两项服务允许您导入 API 蓝图文件以进行托管，甚至可以在编写任何代码之前测试您的 API 设计。
请记住，在编写 API 文档时，要考虑的最重要因素是它对用户的价值。引用 Apiary 的话，“API 的好坏取决于它的文档。”有时可能很难将 API 的完美结构与现有系统的当前结构分开，但重要的是要记住它只是另一个用户界面。虽然当前应用程序的后端架构对前端有一些影响，但我们通常必须找到创造性的解决方案才能为我们的用户提供最佳体验。这与 API 设计之间的唯一区别是我们的目标用户更精通技术，因此当某些事情没有意义时可能不会那么宽容。