HTTP API的6种设计原则

原文地址：https://medium.com/@aldesantis/6-design-principles-for-your-http-apis-560434f9744e

作者：Alessandro Desantis

翻译：高行行

良好的API设计是一门艺术，这一点没有争议。当我们遇到一个经过适当设计的API时，我们会感觉到。就像良好的视觉UI一样，良好的API不仅美观，而且功能强大并且可以节省每个人的时间。基于这种想法，可以说API实际上就是UI。它们也不仅仅适用于机器：由于有人在编程和使用这些机器，因此创建一个用户感到高兴与之交互的API是其开发团队的明智选择，我们应该做出选择。

关于视觉UI的设计原理，有很多资源，也有很多可以从中得到启发的好例子。另一方面，涉及API时，有很多文档说明了用于实现这些协议的不同协议，语言和框架，但是几乎没有足够的材料来说明使某些API易于使用和使用的基本原理和选择。别人的噩梦。

尽管没有什么能比以往更胜一筹，并且每个团队都针对API的出色之处制定了自己的规则，但我们可以通过在API设计中应用一些基本原则来从中受益。这些非常抽象，可以用许多不同的方式实现，但它们应始终指导我们的技术决策。

1. 一致性

一致性意味着相似的端点应该以相似的方式运行，包括在边缘场景中。您应该始终努力在整个API中保持词汇表，URL结构，请求/响应格式和错误处理的一致性。

这提供了几个好处：

• 它使与您的API的交互变得更加简单，因为用户始终知道期望什么，而不必阅读每个端点的文档，而可以随心所欲。
• 它允许编写客户端库，这些客户端库不知道API的确切架构，仅知道您遵守的规则。Stripe API客户端就是一个很好的例子：由于请求和响应的结构始终相同，因此它可以动态构建对象，并且仅在其中一个API规则更改时才需要更新。
• 它创建了一组经过实践检验的准则，在API中实现新功能时可以遵循这些准则。不再讨论使用数字ID还是UUID，因为您将继续使用已有的东西。

一致性可能是您可以在API设计中实现的最有影响力的特征，并且您的用户会因此而爱您。

2. 性能

HTTP API的性能非常棘手。由于最终用户不会直接使用API，因此很容易很长时间就不会注意到性能问题，尤其是在服务器到服务器交互的情况下。不幸的是，由于软件是为人开发的，因此所有类型的性能问题最终都会影响最终用户。

出于通常的原因，我强烈建议您不要进行早期优化：这会减慢MVP的开发速度，并且如果不首先制定正确的指标，就无法知道需要优化产品的哪些部分。您应该基于数据而非本能进行优化。

如此说来，从第一天开始收集数据就非常重要。如今，设置APM工具只需几秒钟，它将为您提供大量有关在现实世界中如何使用API的有用信息。

3. 文献资料

不管您的API多么一致，用户仍然需要他们可以去的地方才能开始使用或获得有关API某些方面或功能的其他详细信息。

此外，API文档不应该只是呈现请求和响应模板。建议添加可能对用户有用的任何信息，例如有关在进行某个API调用时在后台发生的情况或用户可能需要完成其他交易的其他终结点的解释，这是有用的。

API文档的准确性和最新性非常重要。实现此目的的唯一方法是创建工作流，以将文档集成到开发过程中。一个好的方法是将文档检入VCS，并要求开发人员在更改API时对其进行更新。

让开发人员编写文档似乎是浪费时间，但是花在文档上的时间越多，花在回答问题和调查虚假错误报告上的时间就越少。

最后，确保不仅提供文档，而且请查阅。由于它是供人类食用的，因此在阅读文档时要特别注意UI和UX。无需您自己执行此操作，您只需采用Stoplight之类的服务即可为您存储和呈现标准格式的内容。

4. 易用性

虽然在数据库表和API资源之间建立1：1映射并不是天生的错误，但是您应该知道，这不是构建API的唯一方法。实际上，对于复杂的API而言，这通常不是最佳方法，因为这使按正确顺序将正确的一组操作组合在一起的所有负担都落在了用户的肩膀上。

如果您可以简化业务交易以仅需要一个API调用而不是两个API调用，为什么不这样做呢？视觉UI要求在后台发生的每个操作都需要用户输入是不可想象的-但是，当我们要求用户出于懒惰而做时，这正是我们在许多API中所做的。

API的一个示例就是该API，它允许用户添加新的付款方式并将一种付款方式标记为默认付款方式。如果我们希望用户希望添加新方法并立即将其标记为默认属性，则可以向支付方法创建端点添加标记为默认属性，并在一次交易中完成所有操作，而无需两次API调用。这样既节省了开发时间，又节省了带宽。

这种简化并非总是可能的：当您无法预先确定API的确切用例时（例如，在使用公共API的情况下），则应该尽可能地灵活（在上面的示例中，这意味着要添加该字段，还要维护一个单独的端点来设置默认付款方式）。

经验法则是将API的各个方面视为达到目的的手段，即完成业务流程。您如何最好地帮助用户实现该目标？一旦考虑到这一点，设计选择就会变得更加容易。

5. 简单

在简单的，通用的标准和工具之上构建您的API。除非您有充分的理由使用信封，否则不需要信封，架构，API网关或任何其他深奥的解决方案。

HTTP RFC已经为您提供了构建可靠且可互操作的Web服务所需的大多数工具，因此请继续阅读它（是的，虽然很长，但是我可以保证值得）。

坚持基础并做好。简单意味着对人和机器的开销更少，并且出错的空间也更少。例如，以下是使用Stripe API向信用卡收费的方法：

curl https://api.stripe.com/v1/charges \ 
  -u your_api_key: \ 
  -d amount=999 \ 
  -d currency=usd \ 
  -d description="Example charge" \ 
  -d source=tok_visa

它是如此简单，您无需查找文档即可进行操作，并且几乎不可能将其弄乱。这是您要争取的简单性。

（顺便说一下，Stripe API是周到的API设计的绝佳示例，因此，如果有空的话，请看一下API参考。）

6. 演化

传统的Web应用程序一直在更新：设计和添加新功能，改进和简化流行功能，弃用和删除不使用的功能。用户习惯于在不断变化的环境中生活和操作，有时环境会发生巨大变化。

大多数时候，产品在吸引用户采用新功能方面做得非常好：新闻通讯，应用内参观和良好的设计习惯可确保UX不会因最新的全面更新而中断。

另一方面，对于API来说，似乎只有两个可能的选择：要么从不更改接口以免破坏实现，要么不经通知就更改它，从而破坏了大多数客户的工作。发生这种情况是因为API团队通常不会与用户群断开连接，因为它们不会直接与用户互动。

但是，第三个选择是完全可能的：有了正确的基础架构和工具，您就可以拥有以对其用户可管理的方式进行更改的API。您可以使用度量标准来做出有关您公开的界面的明智决定：端点使用频率是多少？最近6个月内，有哪些用户称其为特定的API端点？确保您始终可以回答此类问题，因为它们将使您无需担心用户一天的噩梦就能开发自己的API。

打赏