马斯克称推特的 API 速率限制是他决定放弃收购的核心原因

马斯克曾多次公开表示，他希望知道有多少推特账户是由机器人运营的，因为他觉得可疑账户的数量影响了公司的价值。因此他寻求检测和处理虚假账户的方法。当推特最终提供了马斯克明确要求的 8 个开发者 API 的访问权时，这些 API 的速率限制低于推特向其最大企业客户提供的速率限制。马斯克称，这使得他们无法在任何合理的时间内完成数据分析。

消息来源：The Register

老王点评：看看，对 API 访问提供速率限制有多严重。: D

许多老的 X.Org 组件在本周末有新的发布

上周末，Oracle 的长期 X.Org 贡献者 Alan Coopersmith 对各种旧的、很少维护的 X.Org 项目发布了许多新的更新。这些软件多年来没有任何更新，新的版本大多只是收集了过去几年中的一些随机修复。总的来说，这些更新并没有什么值得兴奋的改进。

消息来源：Phoronix

老王点评：这是觉得 X.org 快被放弃了才最后抢救一次？从另外一方面看，可见 X.org 社区有多冷清了。连随手收到的一些修复都懒得发布个新版本。

Linode 现在提供 Kali Linux 实例

Kali Linux 是一个为渗透测试或黑客而设计的 Linux 发行版。这个基于 Debian 的 Linux 是安全研究人员最喜欢的发行版。它现在可以在 Linode 云上使用了，你可以用它来测试和保护你的生产系统。Linode 云是第一个与 Kali Linux 合作的替代云提供商。

消息来源：ZDNet

老王点评：这是一个跑在公有云上的黑客套装？总觉得哪里不对。

一家中国公司发布了首款 RISC-V 笔记本电脑？

“RISC-V 国际”透露，一家名为“鉴释”的中国公司已经宣布了第一台面向开发者的 RISC-V 笔记本电脑，现已开放预订。据介绍，这个 “ROMA” 开发平台具有四核 RISC-V 处理器，高达 16GB 的内存，最大 256GB 的存储空间，并且可以运行大多数 RISC-V Linux 发行版。有趣的是，这家名为“鉴释”的公司原本是一家开发静态代码分析工具的公司，这个名为“ROMA”的新产品也无法在其中英文网站找到任何链接，只有一个孤儿 预定页，而预定页中提供一个表格，没有确定的价格或预期供应量的信息、甚至连概念图都没有，并且还提到了一些 Web3 和 NFT 的事情。

消息来源：Phoronix

老王点评：这真不是洋葱新闻？

谷歌推出“高级 API 安全”服务

谷歌宣布了“高级 API 安全”的预览版，这是一个新产品，将在谷歌云上推出，旨在检测与 API 有关的安全威胁。该服务可以识别 API 错误配置和检测恶意机器人。配置错误的 API 是造成 API 安全事件的主要原因之一。开发者们越来越依赖 API，但它们也越来越成为攻击的目标。根据一份 2018 年的报告，三分之二的组织正在向公众和合作伙伴暴露了不安全的 API。

消息来源：Tech Crunch

老王点评：一个配置不当的 API，造成的影响可能非常可怕，我想网络安全圈子对这个很有感受。

Linux Mint 21 不准备用 oomd

Linux Mint 21 正在努力争取在今年夏天发布，它是建立在 Ubuntu 22.04 LTS 之上的。但因 Ubuntu 22.04 在 systemd-oomd 上广受批评，Linux Mint 决定不用这个服务来“屠杀”用户的应用。Canonical 公司的开发人员一直在努力修复这个问题，随着最新提出的 SRU 可能会有所改善。

消息来源：Phoronix

老王点评：Mint 做了明智的选择。这根本不是 oomd 的策略问题，而是不经过用户同意，甚至用户没有反对的机会，就被杀了应用。

大家好！几天前我写了篇 小型的个人程序 的文章，里面提到了调用没有文档说明的“秘密” API 很有意思，你需要从你的浏览器中把 cookies 复制出来才能访问。

有些读者问如何实现，因此我打算详细描述下，其实过程很简单。我们还会谈谈在调用没有文档说明的 API 时，可能会遇到的错误和道德问题。

我们用谷歌 Hangouts 举例。我之所以选择它，并不是因为这个例子最有用（我认为官方的 API 更实用），而是因为在这个场景中更有用的网站很多是小网站，而小网站的 API 一旦被滥用，受到的伤害会更大。因此我们使用谷歌 Hangouts，因为我 100% 肯定谷歌论坛可以抵御这种试探行为。

我们现在开始！

第一步：打开开发者工具，找一个 JSON 响应

我浏览了 https://hangouts.google.com，在Firefox的开发者工具中打开“ruby网络rtNetwork/rt/ruby”标签，找到一个 JSON 响应。你也可以使用 Chrome 的开发者工具。

打开之后界面如下图：

找到其中一条 “ 类型 Type ” 列显示为 json 的请求。

为了找一条感兴趣的请求，我找了好一会儿，突然我找到一条 “people” 的端点，看起来是返回我们的联系人信息。听起来很有意思，我们来看一下。

第二步：复制为 cURL

下一步，我在感兴趣的请求上右键，点击 “复制Copy” -> “ 复制为 cURL Copy as cURL ”。

然后我把 curl 命令粘贴到终端并运行。下面是运行结果：

$ curl 'https://people-pa.clients6.google.com/v2/people/?key=REDACTED' -X POST ........ （省略了大量请求标头）
Warning: Binary output can mess up your terminal. Use "--output -" to tell 
Warning: curl to output it to your terminal anyway, or consider "--output 
Warning: <FILE>" to save to a file.

你可能会想 —— 很奇怪，“二进制的输出在你的终端上无法正常显示” 是什么错误？原因是，浏览器默认情况下发给服务器的请求头中有 Accept-Encoding: gzip, deflate 参数，会把输出结果进行压缩。

我们可以通过管道把输出传递给 gunzip 来解压，但是我们发现不带这个参数进行请求会更简单。因此我们去掉一些不相关的请求头。

第三步：去掉不相关的请求头

下面是我从浏览器获得的完整 curl 命令。有很多行！我用反斜杠（\）把请求分开，这样每个请求头占一行，看起来更清晰：

curl 'https://people-pa.clients6.google.com/v2/people/?key=REDACTED' \
-X POST \
-H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:96.0) Gecko/20100101 Firefox/96.0' \
-H 'Accept: */*' \
-H 'Accept-Language: en' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'X-HTTP-Method-Override: GET' \
-H 'Authorization: SAPISIDHASH REDACTED' \
-H 'Cookie: REDACTED'
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'X-Goog-AuthUser: 0' \
-H 'Origin: https://hangouts.google.com' \
-H 'Connection: keep-alive' \
-H 'Referer: https://hangouts.google.com/' \
-H 'Sec-Fetch-Dest: empty' \
-H 'Sec-Fetch-Mode: cors' \
-H 'Sec-Fetch-Site: same-site' \
-H 'Sec-GPC: 1' \
-H 'DNT: 1' \
-H 'Pragma: no-cache' \
-H 'Cache-Control: no-cache' \
-H 'TE: trailers' \
--data-raw 'personId=101777723309&personId=1175339043204&personId=1115266537043&personId=116731406166&extensionSet.extensionNames=HANGOUTS_ADDITIONAL_DATA&extensionSet.extensionNames=HANGOUTS_OFF_NETWORK_GAIA_GET&extensionSet.extensionNames=HANGOUTS_PHONE_DATA&includedProfileStates=ADMIN_BLOCKED&includedProfileStates=DELETED&includedProfileStates=PRIVATE_PROFILE&mergedPersonSourceOptions.includeAffinity=CHAT_AUTOCOMPLETE&coreIdParams.useRealtimeNotificationExpandedAcls=true&requestMask.includeField.paths=person.email&requestMask.includeField.paths=person.gender&requestMask.includeField.paths=person.in_app_reachability&requestMask.includeField.paths=person.metadata&requestMask.includeField.paths=person.name&requestMask.includeField.paths=person.phone&requestMask.includeField.paths=person.photo&requestMask.includeField.paths=person.read_only_profile_info&requestMask.includeField.paths=person.organization&requestMask.includeField.paths=person.location&requestMask.includeField.paths=person.cover_photo&requestMask.includeContainer=PROFILE&requestMask.includeContainer=DOMAIN_PROFILE&requestMask.includeContainer=CONTACT&key=REDACTED'

第一眼看起来内容有很多，但是现在你不需要考虑每一行是什么意思。你只需要把不相关的行删掉就可以了。

我通常通过删掉某行查看是否有错误来验证该行是不是可以删除 —— 只要请求没有错误就一直删请求头。通常情况下，你可以删掉 Accept*、Referer、Sec-*、DNT、User-Agent 和缓存相关的头。

在这个例子中，我把请求删成下面的样子：

curl 'https://people-pa.clients6.google.com/v2/people/?key=REDACTED' \
-X POST \
-H 'Authorization: SAPISIDHASH REDACTED' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Origin: https://hangouts.google.com' \
-H 'Cookie: REDACTED'\
--data-raw 'personId=101777723309&personId=1175339043204&personId=1115266537043&personId=116731406166&extensionSet.extensionNames=HANGOUTS_ADDITIONAL_DATA&extensionSet.extensionNames=HANGOUTS_OFF_NETWORK_GAIA_GET&extensionSet.extensionNames=HANGOUTS_PHONE_DATA&includedProfileStates=ADMIN_BLOCKED&includedProfileStates=DELETED&includedProfileStates=PRIVATE_PROFILE&mergedPersonSourceOptions.includeAffinity=CHAT_AUTOCOMPLETE&coreIdParams.useRealtimeNotificationExpandedAcls=true&requestMask.includeField.paths=person.email&requestMask.includeField.paths=person.gender&requestMask.includeField.paths=person.in_app_reachability&requestMask.includeField.paths=person.metadata&requestMask.includeField.paths=person.name&requestMask.includeField.paths=person.phone&requestMask.includeField.paths=person.photo&requestMask.includeField.paths=person.read_only_profile_info&requestMask.includeField.paths=person.organization&requestMask.includeField.paths=person.location&requestMask.includeField.paths=person.cover_photo&requestMask.includeContainer=PROFILE&requestMask.includeContainer=DOMAIN_PROFILE&requestMask.includeContainer=CONTACT&key=REDACTED'

这样我只需要 4 个请求头：Authorization、Content-Type、Origin 和 Cookie。这样容易管理得多。

第四步：在 Python 中发请求

现在我们知道了我们需要哪些请求头，我们可以把 curl 命令翻译进 Python 程序！这部分是相当机械化的过程，目标仅仅是用 Python 发送与 cUrl 相同的数据。

下面是代码实例。我们使用 Python 的 requests 包实现了与前面 curl 命令相同的功能。我把整个长请求分解成了元组的数组，以便看起来更简洁。

import requests
import urllib

data = [
    ('personId','101777723'), # I redacted these IDs a bit too
    ('personId','117533904'),
    ('personId','111526653'),
    ('personId','116731406'),
    ('extensionSet.extensionNames','HANGOUTS_ADDITIONAL_DATA'),
    ('extensionSet.extensionNames','HANGOUTS_OFF_NETWORK_GAIA_GET'),
    ('extensionSet.extensionNames','HANGOUTS_PHONE_DATA'),
    ('includedProfileStates','ADMIN_BLOCKED'),
    ('includedProfileStates','DELETED'),
    ('includedProfileStates','PRIVATE_PROFILE'),
    ('mergedPersonSourceOptions.includeAffinity','CHAT_AUTOCOMPLETE'),
    ('coreIdParams.useRealtimeNotificationExpandedAcls','true'),
    ('requestMask.includeField.paths','person.email'),
    ('requestMask.includeField.paths','person.gender'),
    ('requestMask.includeField.paths','person.in_app_reachability'),
    ('requestMask.includeField.paths','person.metadata'),
    ('requestMask.includeField.paths','person.name'),
    ('requestMask.includeField.paths','person.phone'),
    ('requestMask.includeField.paths','person.photo'),
    ('requestMask.includeField.paths','person.read_only_profile_info'),
    ('requestMask.includeField.paths','person.organization'),
    ('requestMask.includeField.paths','person.location'),
    ('requestMask.includeField.paths','person.cover_photo'),
    ('requestMask.includeContainer','PROFILE'),
    ('requestMask.includeContainer','DOMAIN_PROFILE'),
    ('requestMask.includeContainer','CONTACT'),
    ('key','REDACTED')
]
response = requests.post('https://people-pa.clients6.google.com/v2/people/?key=REDACTED',
    headers={
        'X-HTTP-Method-Override': 'GET',
        'Authorization': 'SAPISIDHASH REDACTED',
        'Content-Type': 'application/x-www-form-urlencoded',
        'Origin': 'https://hangouts.google.com',
        'Cookie': 'REDACTED',
    },
    data=urllib.parse.urlencode(data),
)

print(response.text)

我执行这个程序后正常运行 —— 输出了一堆 JSON 数据！太棒了！

你会注意到有些地方我用 REDACTED 代替了，因为如果我把原始数据列出来你就可以用我的账号来访问谷歌论坛了，这就很不好了。

运行结束！

现在我可以随意修改 Python 程序，比如传入不同的参数，或解析结果等。

我不打算用它来做其他有意思的事了，因为我压根对这个 API 没兴趣，我只是用它来阐述请求 API 的过程。

但是你确实可以对返回的一堆 JSON 做一些处理。

curlconverter 看起来很强大

有人评论说可以使用 https://curlconverter.com/ 自动把 curl 转换成 Python（和一些其他的语言！），这看起来很神奇 —— 我都是手动转的。我在这个例子里使用了它，看起来一切正常。

追踪 API 的处理过程并不容易

我不打算夸大追踪 API 处理过程的难度 —— API 的处理过程并不明显！我也不知道传给这个谷歌论坛 API 的一堆参数都是做什么的！

但是有一些参数看起来很直观，比如 requestMask.includeField.paths=person.email 可能表示“包含每个人的邮件地址”。因此我只关心我能看懂的参数，不关心看不懂的。

（理论上）适用于所有场景

可能有人质疑 —— 这个方法适用于所有场景吗？

答案是肯定的 —— 浏览器不是魔法！浏览器发送给你的服务器的所有信息都是 HTTP 请求。因此如果我复制了浏览器发送的所有的 HTTP 请求头，那么后端就会认为请求是从我的浏览器发出的，而不是用 Python 程序发出的。

当然，我们去掉了一些浏览器发送的请求头，因此理论上后端是可以识别出来请求是从浏览器还是 Python 程序发出的，但是它们通常不会检查。

这里有一些对读者的告诫 —— 一些谷歌服务的后端会通过令人难以理解（对我来说是）方式跟前端通信，因此即使理论上你可以模拟前端的请求，但实际上可能行不通。可能会遭受更多攻击的大型 API 会有更多的保护措施。

我们已经知道了如何调用没有文档说明的 API。现在我们再来聊聊可能遇到的问题。

问题 1：会话 cookie 过期

一个大问题是我用我的谷歌会话 cookie 作为身份认证，因此当我的浏览器会话过期后，这个脚本就不能用了。

这意味着这种方式不能长久使用（我宁愿调一个真正的 API），但是如果我只是要一次性快速抓取一小组数据，那么可以使用它。

问题 2：滥用

如果我正在请求一个小网站，那么我的 Python 脚本可能会把服务打垮，因为请求数超出了它们的处理能力。因此我请求时尽量谨慎，尽量不过快地发送大量请求。

这尤其重要，因为没有官方 API 的网站往往是些小网站且没有足够的资源。

很明显在这个例子中这不是问题 —— 我认为在写这篇文章的过程我一共向谷歌论坛的后端发送了 20 次请求，他们肯定可以处理。

如果你用自己的账号身份过度访问这个 API 并导致了故障，那么你的账号可能会被暂时封禁（情理之中）。

我只下载我自己的数据或公共的数据 —— 我的目的不是寻找网站的弱点。

请记住所有人都可以访问你没有文档说明的 API

我认为本文最重要的信息并不是如何使用其他人没有文档说明的 API。虽然很有趣，但是也有一些限制，而且我也不会经常这么做。

更重要的一点是，任何人都可以这么访问你后端的 API！每个人都有开发者工具和网络标签，查看你传到后端的参数、修改它们都很容易。

因此如果一个人通过修改某些参数来获取其他用户的信息，这不值得提倡。我认为提供公开 API 的大部分开发者们都知道，但是我之所以再提一次，是因为每个初学者都应该了解。: )

via: https://jvns.ca/blog/2022/03/10/how-to-use-undocumented-web-apis/

作者：Julia Evans 选题：lujun9972 译者：lxbwolf 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

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

如果你正在构建基于 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 头的机制，这种机制允许服务器标记除自身源外的其他任何来源（域、方案或端口）。而对于这些被服务器标识的源，浏览器应该允许我们从它们加载资源。”

(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:WRITE 或 ARTICLE:READ，其中 ARTICLE 是资源，READ 和 WRITE 是动作）。

作用域的划分让我们的 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中国 荣誉推出

GraphQL 是一种查询语言、一个执行引擎，也是一种规范，它让开发人员重新思考如何构建客户端和 API 应用。

GraphQL 是当今软件技术中最大的流行语之一。但它究竟是什么？是像 SQL 一样的查询语言吗？是像 JVM 这样的执行引擎？还是像 XML 这样的规范？

如果你回答上面这些都是，那么你是对的！GraphQL 是一种查询语言的语法、是一种编程语言无关的执行引擎，也是一种不断发展的规范。

让我们深入了解一下 GraphQL 如何成为所有这些东西的，并了解一下人们为什么对它感到兴奋。

查询语言

GraphQL 作为查询语言似乎是合理的 —— 毕竟 “QL” 似乎重要到出现在名称中。但是我们查询什么呢？看一个示例查询请求和相应的响应可能会有所帮助。

以下的用户查询：

{
    user(id: 4) {
        name
        email
        phoneNumber
    }
}

可能会返回下面的 JSON 结果：

{
    "user": {
        "name": "Zach Lendon"
        “email”: “[email protected]”
        “phoneNumber”: “867-5309”
    }
}

想象一下，客户端应用查询用户详细信息、获取结果，并使用它填充配置屏幕。作为查询语言，GraphQL 的核心优势之一是客户端应用可以只请求它需要的数据，并期望以一致的方式返回这些数据。

那么 GraphQL 响应返回的什么呢？这就是执行引擎发挥的作用，通常是以 GraphQL 服务器的形式出现。

执行引擎

GraphQL 执行引擎负责处理 GraphQL 查询并返回 JSON 响应。所有 GraphQL 服务器由两个核心组件组成，分别定义了执行引擎的结构和行为：模式和解析器。

GraphQL 模式是一种自定义类型语言，它公开哪些查询既允许（有效），又由 GraphQL 服务器实现处理。上面用户示例查询的模式可能如下所示：

type User {
    name: String
    email: String
    phoneNumber: String
}

type Query {
    user: User
}

此模式定义了一个返回用户的用户查询。客户端可以通过用户查询请求用户上的任何字段，并且 GraphQL 服务器将仅返回请求的字段。通过使用强类型模式，GraphQL 服务器可以根据定义的模式验证传入的查询，以确保是有效的。

确定查询有效后，就会由 GraphQL 服务器的解析器处理。解析器函数支持每个 GraphQL 类型的每个字段。我们的这个用户查询的示例解析器可能如下所示：

Query: {
    user(obj, args, context, info) {
        return context.db.loadUserById(args.id).then(
            userData => new User(userData)
        )
    }
}

虽然上面的例子是用 JavaScript 编写的，但 GraphQL 服务器可以用任意语言编写。这是因为 GraphQL 也是也是一种规范！

规范

GraphQL 规范定义了 GraphQL 实现必须遵循的功能和特性。作为一个在开放网络基金会的最终规范协议（OWFa 1.0）下提供的开放规范，技术社区可以审查 GraphQL 实现必须符合规范的要求，并帮助制定 GraphQL 的未来。

虽然该规范对 GraphQL 的语法，什么是有效查询以及模式的工作方式进行了非常具体的说明，但它没有提供有关如何存储数据或 GraphQL 服务器应使用哪种编程语言实现的指导。这在软件领域是非常强大的，也是相对独特的。它允许以各种编程语言创建 GraphQL 服务器，并且由于它们符合规范，因此客户端会确切知道它们的工作方式。GraphQL 服务器已经有多种语言实现，人们不仅可以期望像 JavaScript、Java和 C# 这样的语言，还可以使用 Go、Elixir 和 Haskell 等。服务器实现所使用的语言不会成为采用过程的障碍。它不仅存在多种语言实现，而且它们都是开源的。如果没有你选择的语言的实现，那么可以自己实现。

总结

GraphQL 是开源 API 领域中一个令人兴奋的、相对较新的参与者。它将查询语言、执行引擎与开源规范结合在一起，它定义了 GraphQL 实现的外观和功能。

GraphQL 已经开始改变企业对构建客户端和 API 应用的看法。通过将 GraphQL 作为技术栈的一部分，前端开发人员可以自由地查询所需的数据，而后端开发人员可以将客户端应用需求与后端系统架构分离。通常，公司在使用 GraphQL 的过程中，首先会在其现有的后端服务之上构建一个 GraphQL API “层”。这使得客户端应用开始获得他们所追求的性能和运营效率，同时使后端团队有机会确定他们可能需要在 GraphQL 层后面的“幕后”进行哪些更改。通常，这些更改都是为了优化，这些优化有助于确保使用 GraphQL 的应用可以尽可能高效地运行。由于 GraphQL 提供了抽象性，因此系统团队可以进行更改的同时继续在其 GraphQL API 级别上遵守 GraphQL 的“合约”。

由于 GraphQL 相对较新，因此开发人员仍在寻找新颖而激动人心的方法来利用它构建更好的软件解决方案。GraphQL 将如何改变你构建应用的方式，它是否对得起众望所归？只有一种方法可以找到答案 —— 用 GraphQL 构建一些东西！

via: https://opensource.com/article/19/6/what-is-graphql

作者：Zach Lendon 选题：lujun9972 译者：geekpi 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

为了在 Python 中快速构建 API，我主要依赖于 Flask。最近我遇到了一个名为 “API Star” 的基于 Python 3 的新 API 框架。由于几个原因，我对它很感兴趣。首先，该框架包含 Python 新特点，如类型提示和 asyncio。而且它再进一步为开发人员提供了很棒的开发体验。我们很快就会讲到这些功能，但在我们开始之前，我首先要感谢 Tom Christie，感谢他为 Django REST Framework 和 API Star 所做的所有工作。

现在说回 API Star —— 我感觉这个框架很有成效。我可以选择基于 asyncio 编写异步代码，或者可以选择传统后端方式就像 WSGI 那样。它配备了一个命令行工具 —— apistar 来帮助我们更快地完成工作。它支持 Django ORM 和 SQLAlchemy，这是可选的。它有一个出色的类型系统，使我们能够定义输入和输出的约束，API Star 可以自动生成 API 的模式（包括文档），提供验证和序列化功能等等。虽然 API Star 专注于构建 API，但你也可以非常轻松地在其上构建 Web 应用程序。在我们自己构建一些东西之前，所有这些可能都没有意义的。

开始

我们将从安装 API Star 开始。为此实验创建一个虚拟环境是一个好主意。如果你不知道如何创建一个虚拟环境，不要担心，继续往下看。

pip install apistar

（译注：上面的命令是在 Python 3 虚拟环境下使用的）

如果你没有使用虚拟环境或者你的 Python 3 的 pip 名为 pip3，那么使用 pip3 install apistar 代替。

一旦我们安装了这个包，我们就应该可以使用 apistar 命令行工具了。我们可以用它创建一个新项目，让我们在当前目录中创建一个新项目。

apistar new .

现在我们应该创建两个文件：app.py，它包含主应用程序，然后是 test.py，它用于测试。让我们来看看 app.py 文件：

from apistar import Include, Route
from apistar.frameworks.wsgi import WSGIApp as App
from apistar.handlers import docs_urls, static_urls

def welcome(name=None):
    if name is None:
        return {'message': 'Welcome to API Star!'}
    return {'message': 'Welcome to API Star, %s!' % name}


routes = [
    Route('/', 'GET', welcome),
    Include('/docs', docs_urls),
    Include('/static', static_urls)
]

app = App(routes=routes)


if __name__ == '__main__':
    app.main()

在我们深入研究代码之前，让我们运行应用程序并查看它是否正常工作。我们在浏览器中输入 http://127.0.0.1:8080/，我们将得到以下响应：

{"message": "Welcome to API Star!"}

如果我们输入：http://127.0.0.1:8080/?name=masnun

{"message": "Welcome to API Star, masnun!"}

同样的，输入 http://127.0.0.1:8080/docs/，我们将看到自动生成的 API 文档。

现在让我们来看看代码。我们有一个 welcome 函数，它接收一个名为 name 的参数，其默认值为 None。API Star 是一个智能的 API 框架。它将尝试在 url 路径或者查询字符串中找到 name 键并将其传递给我们的函数，它还基于其生成 API 文档。这真是太好了，不是吗？

然后，我们创建一个 Route 和 Include 实例的列表，并将列表传递给 App 实例。Route 对象用于定义用户自定义路由。顾名思义，Include 包含了在给定的路径下的其它 url 路径。

路由

路由很简单。当构造 App 实例时，我们需要传递一个列表作为 routes 参数，这个列表应该有我们刚才看到的 Route 或 Include 对象组成。对于 Route，我们传递一个 url 路径，http 方法和可调用的请求处理程序（函数或者其他）。对于 Include 实例，我们传递一个 url 路径和一个 Routes 实例列表。

路径参数

我们可以在花括号内添加一个名称来声明 url 路径参数。例如 /user/{user_id} 定义了一个 url，其中 user_id 是路径参数，或者说是一个将被注入到处理函数（实际上是可调用的）中的变量。这有一个简单的例子：

from apistar import Route
from apistar.frameworks.wsgi import WSGIApp as App


def user_profile(user_id: int):
    return {'message': 'Your profile id is: {}'.format(user_id)}


routes = [
    Route('/user/{user_id}', 'GET', user_profile),
]

app = App(routes=routes)

if __name__ == '__main__':
    app.main()

如果我们访问 http://127.0.0.1:8080/user/23，我们将得到以下响应：

{"message": "Your profile id is: 23"}

但如果我们尝试访问 http://127.0.0.1:8080/user/some_string，它将无法匹配。因为我们定义了 user_profile 函数，且为 user_id 参数添加了一个类型提示。如果它不是整数，则路径不匹配。但是如果我们继续删除类型提示，只使用 user_profile(user_id)，它将匹配此 url。这也展示了 API Star 的智能之处和利用类型和好处。

包含/分组路由

有时候将某些 url 组合在一起是有意义的。假设我们有一个处理用户相关功能的 user 模块，将所有与用户相关的 url 分组在 /user 路径下可能会更好。例如 /user/new、/user/1、/user/1/update 等等。我们可以轻松地在单独的模块或包中创建我们的处理程序和路由，然后将它们包含在我们自己的路由中。

让我们创建一个名为 user 的新模块，文件名为 user.py。我们将以下代码放入这个文件：

from apistar import Route


def user_new():
    return {"message": "Create a new user"}


def user_update(user_id: int):
    return {"message": "Update user #{}".format(user_id)}


def user_profile(user_id: int):
    return {"message": "User Profile for: {}".format(user_id)}


user_routes = [
    Route("/new", "GET", user_new),
    Route("/{user_id}/update", "GET", user_update),
    Route("/{user_id}/profile", "GET", user_profile),
]

现在我们可以从 app 主文件中导入 user_routes，并像这样使用它：

from apistar import Include
from apistar.frameworks.wsgi import WSGIApp as App

from user import user_routes

routes = [
    Include("/user", user_routes)
]

app = App(routes=routes)

if __name__ == '__main__':
    app.main()

现在 /user/new 将委托给 user_new 函数。

访问查询字符串/查询参数

查询参数中传递的任何参数都可以直接注入到处理函数中。比如 url /call?phone=1234，处理函数可以定义一个 phone 参数，它将从查询字符串/查询参数中接收值。如果 url 查询字符串不包含 phone 的值，那么它将得到 None。我们还可以为参数设置一个默认值，如下所示：

def welcome(name=None):
    if name is None:
        return {'message': 'Welcome to API Star!'}
    return {'message': 'Welcome to API Star, %s!' % name}

在上面的例子中，我们为 name 设置了一个默认值 None。

注入对象

通过给一个请求程序添加类型提示，我们可以将不同的对象注入到视图中。注入请求相关的对象有助于处理程序直接从内部访问它们。API Star 内置的 http 包中有几个内置对象。我们也可以使用它的类型系统来创建我们自己的自定义对象并将它们注入到我们的函数中。API Star 还根据指定的约束进行数据验证。

让我们定义自己的 User 类型，并将其注入到我们的请求处理程序中：

from apistar import Include, Route
from apistar.frameworks.wsgi import WSGIApp as App
from apistar import typesystem


class User(typesystem.Object):
    properties = {
    'name': typesystem.string(max_length=100),
    'email': typesystem.string(max_length=100),
    'age': typesystem.integer(maximum=100, minimum=18)
    }

    required = ["name", "age", "email"]


def new_user(user: User):
    return user


routes = [
    Route('/', 'POST', new_user),
]

app = App(routes=routes)

if __name__ == '__main__':
    app.main()

现在如果我们发送这样的请求：

curl -X POST \
  http://127.0.0.1:8080/ \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{"name": "masnun", "email": "[email protected]", "age": 12}'

猜猜发生了什么？我们得到一个错误，说年龄必须等于或大于 18。类型系允许我们进行智能数据验证。如果我们启用了 docs url，我们还将自动记录这些参数。

发送响应

如果你已经注意到，到目前为止，我们只可以传递一个字典，它将被转换为 JSON 并作为默认返回。但是，我们可以使用 apistar 中的 Response 类来设置状态码和其它任意响应头。这有一个简单的例子：

from apistar import Route, Response
from apistar.frameworks.wsgi import WSGIApp as App


def hello():
    return Response(
    content="Hello".encode("utf-8"),
    status=200,
    headers={"X-API-Framework": "API Star"},
    content_type="text/plain"
    )


routes = [
    Route('/', 'GET', hello),
]

app = App(routes=routes)

if __name__ == '__main__':
    app.main()

它应该返回纯文本响应和一个自定义标响应头。请注意，content 应该是字节，而不是字符串。这就是我编码它的原因。

继续

我刚刚介绍了 API Star 的一些特性，API Star 中还有许多非常酷的东西，我建议通过 Github Readme 文件来了解这个优秀框架所提供的不同功能的更多信息。我还将尝试在未来几天内介绍关于 API Star 的更多简短的，集中的教程。

via: http://polyglot.ninja/api-star-python-3-api-framework/

作者：MASNUN 译者：MjSeven 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出