代码人生

API设计-怎么样才能设计出漂亮的API

代码人生 http://www.she9.com 2019-08-28 11:20 出处:网络 编辑:@技术狂热粉
最近,一位同事问我关于“BeautifulAPI”的例子。我立刻半开玩笑地说:“情人眼里出西施。”当然,为了支持这一点,我很快地阐述了对我来说BeautifulAPI可能对别人来说并完美。这让我想到……有没有什么方法可以对一个

最近,一位同事问我关于“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设计-怎么样才能设计出漂亮的API

 

坚持这一原则将意味着访问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是否属于组织的内部?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

                                             

有了精心设计的API、可靠的支持文档和对开发人员现有工具的良好支持,您每次都会让API的技术消费者感到高兴。如果你遵循了这个博客中的建议,当你被问到一个漂亮的API是什么的时候,你就可以自信地对着镜子说:“魔镜魔镜,谁的API最漂亮?”你就会知道答案;)

 

请关注公众号:程序你好
0

精彩评论

暂无评论...
验证码 换一张
取 消