怎么做API设计

最近，一位同事问我关于“Beautiful API”的例子。我立刻半开玩笑地说:“情人眼里出西施。”当然，为了支持这一点，我很快地阐述了对我来说Beautiful API可能对别人来说并完美。这让我想到……有没有什么方法可以对一个Beautiful API进行分类或量化?如果说情人眼里出西施，那么谁才是API的"情人"呢? 在思考了一会儿之后，我得出结论，有两种:

•使用API来创建应用程序的开发人员。

•客户端应用程序本身，由上述开发人员创建，通过使用API(应用程序使用者)来满足一些需求。

那么，API创建者可以做些什么来让他们满意?

开发人员

如果你还记得Donald Knuth的话，他说过“编程是一种艺术，它告诉另一个人你想让电脑做什么。”“如果我们改变两个词，我们可以将同样的道理应用到API设计中。如果我们将“编程”一词改为“设计API”(2019年，我们将用“system”替换“computer”)，我们会得到以下结果:

“API设计是告诉另一个人自己想让系统做什么的艺术。”

因此，API是关于与人通信的。设计良好的API应该易于使用，从而使开发人员在创建应用程序运行时的体验非常顺畅。最终，一个好的API将使开发人员尽可能快地工作。

在设计一个API时，坚持“最少惊讶原则”，即设计要符合受众的心理模型，不应该有任何惊喜;您的受众应该直观地理解API。换句话说，API创建者应该希望使用您的API最小化开发人员的WTFs/min:

坚持这一原则将意味着访问API对开发人员来说很自然。没有什么是不和谐的。例如，身份验证令牌应该使用标准的安全实践、错误代码和直观的消息等。授权失败也不应该返回一个HTTP 200 OK作为错误状态。

API 产品

在设计API时，应该采用产品思维。毕竟，API是为其他人使用的。不管你是否这么想，不管你是否真的在卖，你手上的产品是要给别人用的。因此，这个产品将有一个生命周期和成功标准。

您的API应该指派一个产品经理来帮助成功采用—API的创建不应该只是Jira的任务。需要培育和发展API，使其被认为是成功的。

然而，培育和发展API可能是困难的。开发人员在提供api时所面临的挑战之一与持续的维护和支持有关。作为开发人员，一旦使用了他们的API，它就变成了一个契约。与任何合同一样，它必须遵循，以避免与消费者的违约。换句话说，作为开发人员，您不能对API进行大规模更改，因为这样会破坏使用者的应用程序。

这将成为一项相当繁重的责任，特别是在业务变化和创新需求变化的情况下。为了减少这些类型的问题，提前花时间在设计上是非常重要的;在保持API契约的同时，通过适当的设计来响应不断变化的需求是可以实现的。

请记住，API契约与API实现具有不同的生命周期。在实现生命周期中突出这种差异的一个很好的例子是AWS的S3 API。AWS首席技术官沃纳•福格尔斯(Werner Vogels)表示:“S3最适合被描述为一架单引擎塞斯纳飞机的起始点，但随着时间的推移，这架飞机被升级为737，然后是一组747客机，一直到现在的空客380客机的庞大机群。”但是，如果您查看API契约，Amazon S3 API的当前版本是2006-03-01。

API First

理想情况下，在为您的API实现任何代码之前，API契约(例如OAS 3.0)被定义为供API使用者检查。注意，这个契约可以在 Stoplight.io之类的工具中定义,甚至代码中的注释，但是API没有实现。

实现应该等到API被其使用者评审和批准之后。例如，如果一个API是开发人员的GUI，并且您将其映射到已接受的UI设计工作流，那么契约就是一个线框图，API消费者就是验证线框图中显示内容的UI用户。一旦修改了契约并使其API消费者满意，就可以开始实现了。

记住，您不是API的用户/消费者，所以得到的验证和反馈越多越好。实现此目的的另一种方法是提供契约的模拟实现，并要求API使用者开始针对模拟编写代码。当使用者尝试使用模拟时，他们可能会看到未被考虑的用例和场景，从而允许在API成为严格的契约之前进行重新设计。

你不是用户，越多的API用户评论API越好(图片来自UX工程师笔记本电脑)

客户端应用

设计API时要考虑的另一个方面是使用API的上下文。例如，作为微服务体系结构的一部分，API是否属于组织的内部?API是否会公开并在移动应用程序中使用?消费应用程序在其中运行的上下文将影响您提供的API类型:

•GraphQL api适合于移动应用程序，有助于避免REST api中出现的闲聊。使用GraphQL，客户端决定他们想要什么数据，如何使用数据，以及他们想要什么格式的数据，而不是遍历多个REST请求(查找应用程序所需的资源的响应)。

•SSE(服务器端事件)，如果您需要将数据从服务器推送到web应用程序。

•gRPC—当您的api是组织内部的而不是web上的(即在微服务体系结构中)，以及当您控制消费者和提供者时。

了解客户机应用程序将运行在何处，将有助于确定应该提供什么API。

UIs 开发人员体验

一旦您的API准备好投入使用，您就可以在开发人员门户中提供所有资产(文档、SDK、代码片段、API定义、端点)，即目标开发人员“闲逛”的地方。

需要注意的是，SDK不应该只是围绕API定义的一层薄薄的外壳，而应该包含示例、用于创建应用程序的构建工具等等。它应该具备所有帮助降低复杂性和增加开发人员体验的功能。

请记住，如果您正在提供一个UI应用程序来支持您的API，那么它只对特定环境中的开发人员有用。今天，采用CI/CD是交付和部署应用程序的公认规范。UI在CI/CD管道的开始和结束时最有帮助，而所有其他中间环境都应该考虑为headless。因此，对于这些无头、高度自动化的环境，提供CLI更有用。因此，在CI/CD管道中，可以保存以下内容:

•API和CLI在所有环境中都很有用

•UI在初始和最终环境中都很有用

提供正确的CLI和GUI体验将有助于增强API的整体开发人员体验。

有了精心设计的API、可靠的支持文档和对开发人员现有工具的良好支持，您每次都会让API的技术消费者感到高兴。