您当前的位置:首页 > 电脑百科 > 程序开发 > 编程百科

完善的 API 的 4 个基本特征

时间:2021-06-16 09:55:55  来源:Linux中国  作者:Tom Wilson

创建一个 API(应用程序接口),我们所要做的远远不止是让它能“正常工作”。

完善的 API 的 4 个基本特征

如果你正在构建基于 C/S 模型的应用程序,那么你需要一个应用程序接口(API)。API 就是一种非常清晰而又明确的定义,它是一个进程process与另一个进程之间明确定义的边界。Web 应用中我们常见的边界定义就是 REST/JSON API。

虽然很多开发者可能主要关注在如何让 API 正常工作(或功能正常),但却还有一些“非功能性”的要求也是需要他们注意的。所有的 API 必须具备的 4 个非功能性的要求是:

  • 安全
  • 文档
  • 验证
  • 测试

 

安全

在软件开发中,安全是最基本的要求。对于 API 开发者来说,API 的安全性主要包含以下 4 个方面:

  1. HTTPS/SSL 证书
  2. 跨域资源共享
  3. 身份认证与 JSON Web 令牌
  4. 授权与作用域

 

1、HTTPS/SSL 证书

Web 应用的黄金标准是使用 SSL 证书的 HTTPS 协议。Let's Encrypt可以帮你达到这一目的。Let's Encrypt 来自于非营利性的互联网安全研究小组(ISRG),它是一个免费的、自动化的、开放的证书颁发机构。

Let's Encrypt 的软件会为你的域(LCTT 译注:包含域名、IP 等信息)生成中央授权证书。而正是这些证书确保了从你的 API 到客户端的数据载荷是点对点加密的。

Let's Encrypt 支持证书管理的多种部署方案。我们可以通过查看 文档来找出最适合自己需要的方案。

 

2、跨域资源共享

跨域资源共享Cross-origin resource sharing(CORS)是一个针对浏览器的安全策略预检。如果你的 API 服务器与发出请求的客户端不在同一个域中,那么你就要处理 CORS。例如,如果你的服务器运行在 api.domain-a.com并且接到一个来自domain-b.com的客户端的请求,那么 CORS 就会(让浏览器)发送一个 HTTP 预检请求,以便查看你的 API 服务是否会接受来自此客户域的客户端请求。

来自 MDN 的定义:

“跨域资源共享(CORS)是一种基于 HTTP 头的机制,这种机制允许服务器标记除自身源外的其他任何来源(域、方案或端口)。而对于这些被服务器标识的源,浏览器应该允许我们从它们加载资源。”

完善的 API 的 4 个基本特征

(MDN文档,CC-BY-SA 2.5)

另外,有很多用于 Node.js的辅助库来帮助 API 开发者处理 CORS。

 

3、身份认证与 JSON Web 令牌

有多种方法可以验证你的 API 中的认证用户,但最好的方法之一是使用 JSON Web 令牌(JWT),而这些令牌使用各种知名的加密库进行签名。

当客户端登录时,身份管理服务会向客户端提供一个 JWT。然后,客户端可以使用这个令牌向 API 发出请求,API 收到请求后,从服务器读取公钥或私密信息来验证这个令牌。

有一些现有的库,可以帮助我们对令牌进行验证,包括 jsonwebtoken。关于 JWT 的更多信息,以及各种语言中对其的支持库,请查看JWT.io。

import jwt from 'jsonwebtoken'

export default function (req, res, next) {
    // req.headers.authorization Bearer token
    const token = extractToken(req)
    jwt.verify(token, SECRET, { algorithms: ['HS256'] }, (err, decoded) => {
        if (err) { next(err) }
        req.session = decoded
        next
    })
}

 

4、授权与作用域

认证(或身份验证)很重要,但授权同样很重要。也就是说,经过验证的客户端是否有权限让服务器执行某个请求呢?这就是作用域的价值所在。当身份管理服务器对客户端进行身份认证,且创建 JWT 令牌时,身份管理服务会给当前客户提供一个作用域,这个作用域将会决定当前经过验证的客户的 API 请求能否被服务器执行。这样也就免去了服务器对访问控制列表的一些不必要的查询。

作用域是一个文本块(通常以空格分隔),用于描述一个 API 端点的访问能力。一般来说,作用域被分为资源与动作。这种模式对 REST/JSON API 很有效,因为它们有相似的 RESOURCE:ACTION结构。(例如,ARTICLE:WRITEARTICLE:READ,其中ARTICLE是资源,READWRITE是动作)。

作用域的划分让我们的 API 能够专注于功能的实现,而不是去考虑各种角色和用户。身份访问管理服务可以将不同的角色和用户分配不同的权限范围,然后再将这些不同的作用域提供给不同的 JWT 验证中的客户。

 

总结

当我们开发和部署 API 时,安全应该一直是最重要的要求之一。虽然安全性是一个比较宽泛的话题,但如果能解决上面四个方面的问题,这对于你的 API 来说,在生产环境中将会表现得更好。

 

文档

有什么能比没有文档更糟糕?过期的文档。

开发者对文档真的是又爱又恨。尽管如此,文档仍然是 API 定义是否完善的一个关键部分。开发者需要从文档中知道如何使用这些 API,且你创建的文档对于开发者如何更好地使用 API 也有着非常巨大的作用。

创建 API 文档,我们需要关注下面三个方面:

  1. 开发者入门文档(自述文件/基本介绍)
  2. 技术参考(规范/说明书)
  3. 使用方法(入门和其他指南)

 

1、入门文档

在构建 API 服务的时候,你需要明确一些事情,比如:这个 API 是做什么的?如何建立开发者环境?如何测试该服务?如何提交问题?如何部署它?

通常我们可以通过自述(README)文件来回答上面的这些问题,自述文件一般放在你的代码库中,用于为开发者提供使用你项目的最基本的起点和说明。

自述文件应该包含:

  • API 的描述
  • 技术参考与指南的链接
  • 如何以开发者的身份设置你的项目
  • 如何测试这个项目
  • 如何部署这个项目
  • 依赖管理
  • 代码贡献指南
  • 行为准则
  • 许可证
  • 致谢

你的自述文件应该简明扼要;你不必解释每一个方面,但要提供足够的信息,以便开发者在熟悉你的项目后可以进一步深入研究。

 

2、技术参考

在 REST/JSON API 中, 每一个具体的端点endpoint都对应一个特定的功能,都需要一个具体的说明文档,这非常重要。文档中会定义 API 的描述,输入和可能的输出,并为各种客户端提供使用示例。

OpenAPI是一个创建 REST/JSON 文档的标准, 它可以指导你完成编写 API 文档所需的各种细节。OpenAPI 还可以为你的 API 生成演示文档。

 

3、使用方法

对于 API 的用户来说,仅仅只有技术说明是不够的。他们还需要知道如何在一些特定的情况和场景下来使用这些 API,而大多数的潜在用户可能希望通过你的 API 来解决他们所遇到的问题。

向用户介绍 API 的一个好的方法是利用一个“开始”页面。“开始”页面可以通过一个简单的用例引导用户,让他们迅速了解你的 API 能给他们能带来的益处。

 

总结

对于任何完善的 API,文档都是一个很关键的组成部分。当你在创建文档时,你需要关注 API 文档中的如何入门、技术参考以及如何快速开始等三个方面,这样你的 API 才算是一个完善的 API。

 

验证

API 开发过程中经常被忽视的一个点就是验证。它是一个验证来自外部来源的输入的过程。这些来源可以是客户端发送过来的 JSON 数据,或者是你请求别人的服务收到的响应数据。我们不仅仅要检查这些数据的类型,还要确保这些数据确实是我们要的数据,这样可以消除很多潜在的问题。了解你的边界以及你能控制的和不能控制的东西,对于 API 的数据验证来说是一个很重要的方面。

最好的策略是在进入数据逻辑处理之前,在你能控制的边界的边缘处进行数据的验证。当客户端向你的 API 发送数据时,你需要对该数据做出任何处理之前应用你的验证,比如:确保 Email 是真实的邮件地址、日期数据有正确的格式、字符串符合长度要求。

这种简单的检查可以为你的应用增加安全性和一致性。还有,当你从某个服务接收数据时,比如数据库或缓存,你需要重新验证这些数据,以确保返回的结果符合你的数据检查。

你可以自己手写这些校验逻辑,当然也可以用像 Lodash或Ramda这样的函数库,它们对于一些小的数据对象非常有用。像Joi、Yup或Zod这样的验证库效果会更好,因为它们包含了一些常见的验证方法,可以节省你的时间和精力。除此,它们还能创建一个可读性强的模式。如果你需要看看与语言无关的东西,请看JSON Schema。

 

总结

数据验证虽然并不显眼和突出(LCTT 译注:跟 API 的功能实现以及其他几个方面比),但它可以帮你节省大量的时间。如果不做验证,这些时间将可能被用于故障排除和编写数据迁移脚本。真的不要相信你的客户端会发送干净的数据给你,也不要让验证不通过的数据渗入到你的业务逻辑或持久数据存储中去。花点时间验证你的 API 收到的数据和请求到的响应数据,虽然在前期你可能会感到一些挫折和不适,但这总比你在后期花大量时间去做各种数据收紧管制、故障排除等要容易得多。

 

测试

测试是软件开发中的最佳实践,它应该是最主要的非功能性的要求。对于包括 API 在内的任何项目,确定测试策略都是一个挑战,因为你自始至终都要掌握各种约束,以便相应的来制定你的测试策略。

集成测试Integration testing是测试 API 的最有效的方法之一。在集成测试模式中,开发团队会创建一个测试集用来覆盖应用流程中的某些部分,从一个点到另一个点。一个好的集成测试流程包括测试 API 的入口点以及模拟请求到服务端的响应。搞定这两点,你就覆盖了整个逻辑,包括从 API 请求的开始到模拟服务器的响应,并返回数据给 API。

虽然使用的是模拟,但这种方法让能我们专注于代码逻辑层,而不需要去依赖后端服务和展示逻辑来进行测试。没有依赖的测试会更加可靠、更容易实现自动化,且更容易被接入持续集成管道流。

集成测试的实施中,我会用 Tape、Test-server和Fetch-mock。这些库让我们能够从 API 的请求到数据的响应进行隔离测试,使用 Fetch-mock 还可以将出站请求捕获到持久层。

 

总结

虽然其他的各种测试和类型检查对 API 也都有很好的益处,但集成测试在流程效率、构建和管理时间方面却有着更大的优势。使用 Fetch-mock 这样的工具,可以在服务边界提供一个干净的模拟场景。

 

专注于基础

不管是设计和构建应用程序还是 API,都要确保包含上面的四个基本要素。它们并不是我们唯一需要考虑的非功能性需求,其他的还包括应用监控、日志和 API 管理等。即便如此,安全、文档、验证和测试这四个基本点,对于构建任何使用场景下的完善 API 都是至关重要的关注点。

via: https://opensource.com/article/21/5/successful-apis

作者:Tom Wilson选题:lujun9972译者:ywxgod校对:wxy

本文由 LCTT原创编译,linux中国荣誉推出



Tags: API   点击:()  评论:()
声明:本站部分内容及图片来自互联网,转载是出于传递更多信息之目的,内容观点仅代表作者本人,如有任何标注错误或版权侵犯请与我们联系(Email:2595517585@qq.com),我们将及时更正、删除,谢谢。
▌相关推荐
过去几个月里,我一直在对付一个流行健身品牌的 API,最后发现自己陷入了一种卡夫卡式的噩梦。程序员都喜欢挑战,优秀的程序员一定要征服种种挑战。我一直觉得自己是一个非常优秀...【详细内容】
2021-07-22  Tags: API  点击:(99)  评论:(0)  加入收藏
作者 | edmz译者 | 王强策划 | 万佳多年来,我已经为很多 API 实现了客户端。为此,我整理了一份清单,列出了一些可以改善开发体验的小技巧。这些想法大都与 API 设计或架构无关...【详细内容】
2021-06-29  Tags: API  点击:(132)  评论:(0)  加入收藏
创建一个 API(应用程序接口),我们所要做的远远不止是让它能“正常工作”。如果你正在构建基于 C/S 模型的应用程序,那么你需要一个应用程序接口(API)。API 就是一种非常清晰而又明...【详细内容】
2021-06-16  Tags: API  点击:(148)  评论:(0)  加入收藏
今天又要给大家介绍一个 Spring Boot 中的组件 --HandlerMethodReturnValueHandler。在前面的文章中(如何优雅的实现 Spring Boot 接口参数加密解密?),松哥已经和大家介绍过如何...【详细内容】
2021-03-24  Tags: API  点击:(297)  评论:(0)  加入收藏
使用 HTTPie 调试 API,这是一个用 Python 写的易用的命令行工具。-- Moshe Zadka(作者)HTTPie 是一个非常易用、易于升级的 HTTP 客户端。它的发音为 “aitch-tee-tee-pie”...【详细内容】
2020-08-26  Tags: API  点击:(66)  评论:(0)  加入收藏
一、Debug 调试方法Node 的调试方法有很多,主要分为安装 node-inspect 包调试、用 Chrome DevTools 调试和 IDE 调试,可以在官网的 Docs Debugging Guide 查看安装方法。下面...【详细内容】
2020-08-24  Tags: API  点击:(69)  评论:(0)  加入收藏
1. 概述我们曾分享过《基于 GoogleMap 离线API在内网中加载离线卫星地图的方法》一文,在该文中我们分享了将GoogleMap离线API源码部署到本地的方法。那么这个GoogleMap离线AP...【详细内容】
2020-07-21  Tags: API  点击:(114)  评论:(0)  加入收藏
想知道API的使用在当今的软件开发过程中有多普遍?那就去问问工程师们在他们的项目中集成了多少API吧。大多数开发团队可能不知道确切的答案。然而我们知道,从分析工具到地图应用和云托管,现代应用程序都使用了大量的内部...【详细内容】
2020-06-25  Tags: API  点击:(45)  评论:(0)  加入收藏
Apache ShardingSphere 的 5.x 版本正在开发中,其中 API 的设计是重中之重。目前大部分 API 都已定型,对于用户使用最广泛的分片算法 API,目前也已经做了较大幅度的更新。5.x...【详细内容】
2020-06-15  Tags: API  点击:(151)  评论:(0)  加入收藏
前几天,作者遇到了这样一种情况,需要在一个让web3.py几乎不可能工作的环境中使用Python与Ethereum网络进行通信。...【详细内容】
2020-04-23  Tags: API  点击:(61)  评论:(0)  加入收藏
▌简易百科推荐
摘 要 (OF作品展示)OF之前介绍了用python实现数据可视化、数据分析及一些小项目,但基本都是后端的知识。想要做一个好看的可视化大屏,我们还要学一些前端的知识(vue),网上有很多比...【详细内容】
2021-12-27  项目与数据管理    Tags:Vue   点击:(1)  评论:(0)  加入收藏
程序是如何被执行的  程序是如何被执行的?许多开发者可能也没法回答这个问题,大多数人更注重的是如何编写程序,却不会太注意编写好的程序是如何被运行,这并不是一个好...【详细内容】
2021-12-23  IT学习日记    Tags:程序   点击:(9)  评论:(0)  加入收藏
阅读收获✔️1. 了解单点登录实现原理✔️2. 掌握快速使用xxl-sso接入单点登录功能一、早期的多系统登录解决方案 单系统登录解决方案的核心是cookie,cookie携带会话id在浏览器...【详细内容】
2021-12-23  程序yuan    Tags:单点登录(   点击:(8)  评论:(0)  加入收藏
下载Eclipse RCP IDE如果你电脑上还没有安装Eclipse,那么请到这里下载对应版本的软件进行安装。具体的安装步骤就不在这赘述了。创建第一个标准Eclipse RCP应用(总共分为六步)1...【详细内容】
2021-12-22  阿福ChrisYuan    Tags:RCP应用   点击:(7)  评论:(0)  加入收藏
今天想简单聊一聊 Token 的 Value Capture,就是币的价值问题。首先说明啊,这个话题包含的内容非常之光,Token 的经济学设计也可以包含诸多问题,所以几乎不可能把这个问题说的清...【详细内容】
2021-12-21  唐少华TSH    Tags:Token   点击:(9)  评论:(0)  加入收藏
实现效果:假如有10条数据,分组展示,默认在当前页面展示4个,点击换一批,从第5个开始继续展示,到最后一组,再重新返回到第一组 data() { return { qList: [], //处理后...【详细内容】
2021-12-17  Mason程    Tags:VUE   点击:(14)  评论:(0)  加入收藏
什么是性能调优?(what) 为什么需要性能调优?(why) 什么时候需要性能调优?(when) 什么地方需要性能调优?(where) 什么时候来进行性能调优?(who) 怎么样进行性能调优?(How) 硬件配...【详细内容】
2021-12-16  软件测试小p    Tags:性能调优   点击:(19)  评论:(0)  加入收藏
Tasker 是一款适用于 Android 设备的高级自动化应用,它可以通过脚本让重复性的操作自动运行,提高效率。 不知道从哪里听说的抖音 app 会导致 OLED 屏幕烧屏。于是就现学现卖,自...【详细内容】
2021-12-15  ITBang    Tags:抖音防烧屏   点击:(23)  评论:(0)  加入收藏
11 月 23 日,Rust Moderation Team(审核团队)在 GitHub 上发布了辞职公告,即刻生效。根据公告,审核团队集体辞职是为了抗议 Rust 核心团队(Core team)在执行社区行为准则和标准上...【详细内容】
2021-12-15  InfoQ    Tags:Rust   点击:(24)  评论:(0)  加入收藏
一个项目的大部分API,测试用例在参数和参数值等信息会有很多相似的地方。我们可以复制API,复制用例来快速生成,然后做细微调整既可以满足我们的测试需求1.复制API:在菜单发布单...【详细内容】
2021-12-14  AutoMeter    Tags:AutoMeter   点击:(20)  评论:(0)  加入收藏
最新更新
栏目热门
栏目头条