原文链接:https://www.sitepoint.com/rest-api/[1]
作者:https://www.sitepoint.com/author/craig-buckler/[2]
什么是REST API?REST是「Representational State Transfer(表现层状态转移)」的缩写 - 对最常用的网络服务技术几乎是毫无意义的描述。REST API是两个计算机系统在web浏览器和服务器中使用HTTP技术进行通信的一种方式。
在两个或多个系统之间共享数据一直是软件开发的一个基本要求。比如说,考虑购买汽车保险。你的保险公司必须获得关于你和你的车辆的信息,所以他们要求从汽车登记机构、信贷机构、银行和其他系统获得数据。所有这些都是实时透明地发生的,以确定保险公司是否能提供一个有竞争力的保单。
API(应用程序接口)通过为系统之间的对话提供接口来帮助这种类型的通信。REST只是一种被广泛采纳的API风格,我们用它来与内部和外部以一种一致的和可预测的方式进行沟通。它可以比作我们以前寄信时用邮票、地址和信封的方式,以确保信件被送达和阅读。
REST是人们在web系统中常用的交互方式。例如,在一个社交媒体应用中检索和更新账户信息。
在你的浏览器中打开以下链接,从Open Trivia Database[3]中请求一个随机的计算机问题:
https://opentdb.com/api.php?amount=1&category=18[4]
这是一个作为RESTful网络服务实现的公共API(它遵循REST公约)。你的浏览器将展示一个单独的JSON格式的问答问题,并附有答案。比如说:
{
"response_code": 0,
"results": [
{
"category": "Science: Computers",
"type": "multiple",
"difficulty": "easy",
"question": "What does GHz stand for?",
"correct_answer": "Gigahertz",
"incorrect_answers": [
"Gigahotz",
"Gigahetz",
"Gigahatz"
]
}
]
}
你可以使用任意HTTP客户端,来请求同样的URL并得到响应,比如使用curl[5]:
curl "https://opentdb.com/api.php?amount=1&category=18"
HTTP客户端库可以在所有流行的语言和运行时中使用,包括JavaScript、Node.js和Deno中的Fetch[6]以及PHP中的file_get_contents()[7]。JSON响应是机器可读的,因此可以在输出HTML或其他格式之前被进行解析和使用。
多年来,各种数据通信标准已经发展起来。你可能遇到过的选择包括CORBA[8],SOAP[9],或者 XML-RPC[10]。大多数都确定了严格的消息传递规则。
REST是由Roy Fielding在2000年定义[11]的,比其他的要简单得多。它不是一个标准,而是一套关于RESTful网络服务的建议和约束。其中包括:
一个RESTful网络服务请求包括:
https://mydomain/user/123?format=json
。/user/
的GET请求返回系统中的注册用户列表。/user/
的POST请求使用body
对象创建了一个ID为123
的用户。该响应会返回ID。/user/123
的PUT请求使用body
对象更新用户123
。/user/123
的GET请求返回用户123
的详情。/user/123
的DELETE请求删除用户123
。cookies
等信息可以包含在HTTP请求头中。<form>
提交或者发送单独的JSON编码的数据字符串等方式相同。API-Request.png
响应的有效负载可以是任何实用的东西:数据、HTML、图像、音频文件等等。数据响应通常是JSON编码,但也可以使用XML,CSV,简单字符串或任何其他格式。你可以允许在请求中指定返回格式。比如说,/user/123?format=json
或者 /user/123?format=xml
。
还应该在响应头中设置适当的HTTP状态码[12]。200 OK
用于成功的请求,尽管当记录被创建时也可以返回201 Created
。当发生错误时应该返回适当的状态码,比如说400 Bad Request
,404 Not Found
,401 Unauthorized
等等。
其他HTTP头部可以被设置包括Cache-Control
或Expires
,以指定响应在被视为过期之前可以缓存多长时间。
然而,并没有严格的规则。端点URL、HTTP方法、body对象和响应类型可以随心所欲地实现。例如,POST、PUT和PATCH通常可以互换使用,如有必要任何一个都可以用来创建或更新记录。
下面的Node.js
代码使用Express
框架创建了一个RESTful网络服务。一个单一的/hello/
端点对HTTP GET请求作出响应。
确保已安装Node.js
,创建名为restapi
的新文件夹。在该文件夹中创建一个新的package.json
文件,内容如下:
{
"name": "restapi",
"version": "1.0.0",
"description": "REST test",
"scripts": {
"start": "node ./index.js"
},
"dependencies": {
"express": "4.18.1"
}
}
在命令行中运行npm install
来拉取依赖,然后创建index.js
文件,包括以下代码:
// simple Express.js RESTful API
'use strict';
// initialize
const
port = 8888,
express = require('express'),
app = express();
// /hello/ GET request
app.get('/hello/:name?', (req, res) =>
res.json(
{ message: `Hello ${req.params.name || 'world'}!` }
)
);
// start server
app.listen(port, () =>
console.log(`Server started on port ${port}`);
);
使用npm start
从命令行启动该应用程序,并在浏览器中打开http://localhost:8888/hello/
。响应GET请求时,会显示以下JSON:
{
"message": "Hello world!"
}
API也允许自定义名字,因此http://localhost:8888/hello/everyone/
会返回:
{
"message": "Hello everyone!"
}
考虑在浏览器中启动以下HTML页面,URL是http://localhost:8888/
:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>REST test</title>
</head>
<body>
<script>
fetch('http://localhost:8888/hello/')
.then((response) => {
return response.json();
})
.then((json) => {
console.log(json);
});
</script>
</body>
</html>
fetch
调用发出同样的API请求,浏览器控制台显示{ message: "Hello world!" }
,正如你所期望的那样。
然而,假设你的RESTful网络服务现在被放在网络上,域名是http://mydomain.com/hello/
。页面的JavaScript fetch()
URL也相应地改变了,但在浏览器中打开http://localhost:8888/
,现在会返回控制台错误「Cross-Origin Request Blocked」。
为了安全起见,浏览器只允许客户端的XMLHttpRequest
和Fetch API
调用页面所在的同域请求。
幸运的是,跨源资源共享[13](CORS)使我们能够规避这一安全限制。设置Access-Control-Allow-Origin
HTTP响应头来告诉浏览器允许该请求。它可以设置为一个特定的域,或者设置为所有的域*
。
可以更改网络服务器API代码,以允许运行在任何域名的任何客户端脚本进行访问:
// /hello/ GET request
app.get('/hello/:name?', (req, res) =>
res
.append('Access-Control-Allow-Origin', '*')
.json(
{ message: `Hello ${req.params.name || 'world'}!` }
)
);
或者,Express.js
中间件函数可以将头部附加到每个端点请求:
// enable CORS
app.use((req, res, next) => {
res.append('Access-Control-Allow-Origin', '*');
next();
});
// /hello/ GET request
// ...
注意,浏览器向REST API发出两个请求:
OPTIONS
请求确定Access-Control-Allow-Origin
HTTP响应头是否有效。当你的服务器收到一个OPTIONS
请求方法时,它可以设置Access-Control-Allow-Origin
HTTP响应头返回一个假的空响应,以确保工作不被重复。
REST的成功很大程度上归功于它的简单性。开发人员可以自由地实现RESTful API,但这可能会导致进一步的挑战。要深入了解实现策略,请看13个构建RESTful API的最佳实践[14]。
考虑下面的端点:
/user/123
/user/id/123
/user/?id=123
所有这些都是为用户123
获取数据的有效选项。当你有更复杂的操作时,组合的数量会进一步增加。
归根结底,你如何格式化URL并不重要,但整个API的一致性很重要。这对有许多开发人员的大型代码库来说是个挑战。
API的变化是不可避免的,但端点的URL永远不应该失效,否则会破坏使用它们的应用程序。
为了避免兼容性问题,API通常是有版本的。例如,/2.0/user/123
取代了/user/123
。新的和旧的端点都可以保持活跃。不幸的是,这样就有必要维护多个历史API。旧的版本最终可以被废弃,但整个过程需要仔细规划。
上面显示的测试API是开放的:任何系统都可以在未经授权的情况下获取数据。这对于访问私有数据或允许更新和删除请求的API是不可行的。
与RESTful API处于同域的客户端应用程序将像其他HTTP请求一样发送和接收cookies
。(请注意,旧版浏览器中的Fetch()
需要设置credentials
初始选项)。因此,一个API请求可以被验证,以确保一个用户已经登录并拥有适当的权限。
第三方应用程序必须使用替代的授权方法。常见的认证选项[15]包括:
username:password
字符串的 HTTPAuthorization
头。因为base64很容易被解码,基本(Basic)认证应该只和其他安全机制一起使用,比如HTTPS/SSL。API身份验证将根据使用上下文而有所不同:
RESTful API提供了另一种访问和操作你的应用程序的途径。即使它不是一个引人注目的黑客目标,一个行为不良的客户端也可能每秒发送数以千计的请求,并使你的服务器崩溃。
安全性超出了本文的范围,但常见的最佳实践包括:
DELETE
选项。RESTful APIs受到其实现的限制。响应可能包含比你需要的更多的数据,或者需要进一步的请求来访问所有数据。
考虑一个RESTful API,它提供对作者和书籍数据的访问。为了显示前10名畅销书的数据,客户端可以:
/book/
的详细信息(最畅销的在前)。响应包含有每个作者ID的书籍列表。/author/{id}
请求以获取每个作者的详细信息。这被称为「N+1问题」;必须为父请求中的每个结果提出N个API请求。
为了避免不必要的大的响应,可以调整API使作者的细节是可选的。例如,?author_details=full
。API作者需要满足的选项的数量可能会变得令人困惑。
REST的难题导致Facebook创建了GraphQL--一种网络服务查询语言。把它看作是网络服务的SQL:一个单一的请求定义了你所需要的数据以及你希望它如何返回。
GraphQL解决了RESTful APIs带来的一些挑战,尽管它引入了其他挑战。例如,很难对GraphQL响应进行缓存。
你的客户不太可能有与Facebook类似的问题,所以一旦RESTful API发展到超出其实际限制时,GraphQL可能值得考虑。
有许多工具可以帮助所有语言的RESTful API开发。值得注意的选项包括:
还有大量的公共REST API,集合了笑话、货币转换、地理编码、政府数据以及你能想到的每一个主题。许多是免费的,尽管有些需要你注册一个API密钥或使用其他认证方法。分类列表包括:
在实现你自己的网络服务之前,在你自己的项目中尝试使用一些RESTful API。或者考虑跟随Facebook、GitHub、Google和其他许多巨头的脚步,建立一个属于自己的RESTful API。
下一篇文章中,会翻译分享13个构建RESTful API的最佳实践[27],欢迎关注。
以上就是全部内容,如果对你有所帮助,欢迎点赞收藏转发~
[1]
https://www.sitepoint.com/rest-api/: https://www.sitepoint.com/rest-api/
[2]
https://www.sitepoint.com/author/craig-buckler/: https://www.sitepoint.com/author/craig-buckler/
[3]
Open Trivia Database: https://opentdb.com/
[4]
https://opentdb.com/api.php?amount=1&category=18: https://opentdb.com/api.php?amount=1&category=18
[5]
curl: https://curl.se/
[6]
Fetch: https://developer.mozilla.org/zh-CN/docs/Web/API/Fetch_API
[7]
file_get_contents(): https://www.php.net/manual/en/function.file-get-contents.php
[8]
CORBA: https://www.corba.org/
[9]
SOAP: https://en.wikipedia.org/wiki/SOAP
[10]
XML-RPC: http://xmlrpc.com/
[11]
REST是由Roy Fielding在2000年定义: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style
[12]
HTTP状态码: https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Status
[13]
跨源资源共享: https://developer.mozilla.org/zh-CN/docs/Web/HTTP/CORS
[14]
13个构建RESTful API的最佳实践: https://www.sitepoint.com/build-restful-apis-best-practices/
[15]
认证选项: https://swagger.io/docs/specification/authentication/
[16]
HTTP基本身份验证: https://swagger.io/docs/specification/authentication/basic-authentication/
[17]
API密钥: https://swagger.io/docs/specification/authentication/api-keys/
[18]
OAuth: https://oauth.net/
[19]
JSON Web Tokens (JWT): https://jwt.io/
[20]
Swagger: https://swagger.io/
[21]
Postman: https://www.getpostman.com/downloads/
[22]
Hoppscotch: https://hoppscotch.io/
[23]
Any API: https://any-api.com/
[24]
API list: https://apilist.fun/
[25]
Public APIs: https://github.com/public-apis/public-apis
[26]
Google APIs Explorer: https://developers.google.com/apis-explorer/
[27]
13个构建RESTful API的最佳实践: https://www.sitepoint.com/build-restful-apis-best-practices/