前言

什么是REST API？REST是Representational State Transfer（体现层状态转移）的缩写 - 对最罕用的网络服务技术简直是毫无意义的形容。REST API是两个计算机系统在web浏览器和服务器中应用HTTP技术进行通信的一种形式。

在两个或多个零碎之间共享数据始终是软件开发的一个根本要求。比如说，思考购买汽车保险。你的保险公司必须取得对于你和你的车辆的信息，所以他们要求从汽车注销机构、信贷机构、银行和其余零碎取得数据。所有这些都是实时通明地产生的，以确定保险公司是否能提供一个有竞争力的保单。

API（利用程序接口）通过为零碎之间的对话提供接口来帮忙这种类型的通信。REST只是一种被宽泛驳回的API格调，咱们用它来与外部和内部以一种统一的和可预测的形式进行沟通。它能够比作咱们以前寄信时用邮票、地址和信封的形式，以确保函件被送达和浏览。

REST是人们在web零碎中罕用的交互方式。例如，在一个社交媒体利用中检索和更新账户信息。

REST API示例

在你的浏览器中关上以下链接，从Open Trivia Database中申请一个随机的计算机问题：

https://opentdb.com/api.php?amount=1&category=18

这是一个作为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：

curl "https://opentdb.com/api.php?amount=1&category=18"

HTTP客户端库能够在所有风行的语言和运行时中应用，包含JavaScript、Node.js和Deno中的Fetch以及PHP中的file_get_contents()。JSON响应是机器可读的，因而能够在输入HTML或其余格局之前被进行解析和应用。

REST APIs和Rest

多年来，各种数据通信规范曾经倒退起来。你可能遇到过的抉择包含CORBA，SOAP，或者 XML-RPC。大多数都确定了严格的消息传递规定。

REST是由Roy Fielding在2000年定义的，比其余的要简略得多。它不是一个规范，而是一套对于RESTful网络服务的倡议和束缚。其中包含：

  • 客户服务器拆散模式（Client-Server）：零碎A向零碎B托管的URL收回HTTP申请，并返回一个响应。这与浏览器的工作形式雷同。浏览器对一个特定的URL发出请求，该申请被转发到一个web服务器，该服务器通常返回一个HTML页面。该页面可能蕴含对图片、样式表和JavaScript的援用，从而产生进一步的申请和响应。
  • 无状态（Stateless）：REST是无状态的：客户端申请应该蕴含响应所需的所有信息。换句话说，应该能够依照任何程序收回两个或更多的HTTP申请，并且会收到雷同的响应（除非API被设计为返回随机响应）。
  • 可缓存（Cacheable）：响应应该被定义为可缓存或不可缓存。缓存能够进步性能，因为没有必要为同一个URL从新生成一个响应。在某个时间段特定于某个用户的私人数据通常不会被缓存。
  • 分层（Layered）：申请的客户端不须要晓得它是否在与理论的服务器、代理或任何其余中间人进行通信。

创立RESTful网络服务

一个RESTful网络服务申请包含：

  1. 端点URL。实现RESTful API的应用程序将定义一个或多个带有域名、端口、门路、和/或查问字符串的URL端点，例如，https://mydomain/user/123?format=json。
  2. HTTP办法。不同的HTTP办法能够在任何端点上应用，这些办法映射到应用程序的创立、读取、更新和删除（CRUD）操作：
| HTTP办法 | CRUD | 行为 || --- | --- | --- || GET | 读取 | 返回申请数据 || POST | 创立 | 创立一个新记录 || PUT 或者 PATCH | 更新 | 更新已存在的记录 || DELETE | 删除 | 删除已存在的记录 |比方：- 对`/user/`的GET申请返回零碎中的注册用户列表。- 对`/user/`的POST申请应用`body`对象创立了一个ID为`123`的用户。该响应会返回ID。- 对`/user/123`的PUT申请应用`body`对象更新用户`123`。- 对`/user/123`的GET申请返回用户`123`的详情。- 对`/user/123`的DELETE申请删除用户`123`。
  1. HTTP头部。认证令牌或cookies等信息能够蕴含在HTTP申请头中。
  2. Body对象。数据通常在HTTP主体中传输，该形式与HTML<form>提交或者发送独自的JSON编码的数据字符串等形式雷同。

REST API响应

响应的无效负载能够是任何实用的货色：数据、HTML、图像、音频文件等等。数据响应通常是JSON编码，但也能够应用XML，CSV，简略字符串或任何其余格局。你能够容许在申请中指定返回格局。比如说，/user/123?format=json 或者 /user/123?format=xml 。

还应该在响应头中设置适当的HTTP状态码。200 OK用于胜利的申请，只管当记录被创立时也能够返回201 Created 。当产生谬误时应该返回适当的状态码，比如说400 Bad Request，404 Not Found，401 Unauthorized等等。

其余HTTP头部能够被设置包含Cache-Control或Expires，以指定响应在被视为过期之前能够缓存多长时间。

然而，并没有严格的规定。端点URL、HTTP办法、body对象和响应类型能够得心应手地实现。例如，POST、PUT和PATCH通常能够调换应用，如有必要任何一个都能够用来创立或更新记录。

Hello World示例

上面的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';// initializeconst  port = 8888,  express = require('express'),  app = express();// /hello/ GET requestapp.get('/hello/:name?', (req, res) =>  res.json(    { message: `Hello ${req.params.name || 'world'}!` }  ));// start serverapp.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!"}

客户端REST申请和CORS

思考在浏览器中启动以下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 调用页面所在的同域申请。

侥幸的是，跨源资源共享（CORS）使咱们可能躲避这一平安限度。设置Access-Control-Allow-OriginHTTP响应头来通知浏览器容许该申请。它能够设置为一个特定的域，或者设置为所有的域*。

能够更改网络服务器API代码，以容许运行在任何域名的任何客户端脚本进行拜访：

// /hello/ GET requestapp.get('/hello/:name?', (req, res) =>  res    .append('Access-Control-Allow-Origin', '*')    .json(      { message: `Hello ${req.params.name || 'world'}!` }    ));

或者，Express.js中间件函数能够将头部附加到每个端点申请：

// enable CORSapp.use((req, res, next) => {  res.append('Access-Control-Allow-Origin', '*');  next();});// /hello/ GET request// ...

留神，浏览器向REST API收回两个申请：

  1. 对同一URL的HTTP OPTIONS申请确定Access-Control-Allow-Origin HTTP响应头是否无效。
  2. 理论的REST调用。

当你的服务器收到一个OPTIONS申请办法时，它能够设置Access-Control-Allow-Origin HTTP响应头返回一个假的空响应，以确保工作不被反复。

REST API挑战

REST的胜利很大水平上归功于它的简略性。开发人员能够自在地实现RESTful API，但这可能会导致进一步的挑战。要深刻理解实现策略，请看13个构建RESTful API的最佳实际。

端点共识

思考上面的端点：

  • /user/123
  • /user/id/123
  • /user/?id=123

所有这些都是为用户123获取数据的无效选项。当你有更简单的操作时，组合的数量会进一步减少。

归根结底，你如何格式化URL并不重要，但整个API的一致性很重要。这对有许多开发人员的大型代码库来说是个挑战。

REST API版本控制

API的变动是不可避免的，但端点的URL永远不应该生效，否则会毁坏应用它们的应用程序。

为了防止兼容性问题，API通常是有版本的。例如，/2.0/user/123取代了/user/123。新的和旧的端点都能够放弃沉闷。可怜的是，这样就有必要保护多个历史API。旧的版本最终能够被废除，但整个过程须要认真布局。

REST API认证

下面显示的测试API是凋谢的：任何零碎都能够在未经受权的状况下获取数据。这对于拜访公有数据或容许更新和删除申请的API是不可行的。

与RESTful API处于同域的客户端应用程序将像其余HTTP申请一样发送和接管cookies。(请留神，旧版浏览器中的Fetch()须要设置credentials初始选项）。因而，一个API申请能够被验证，以确保一个用户曾经登录并领有适当的权限。

第三方应用程序必须应用代替的受权办法。常见的认证选项包含：

  • HTTP根本身份验证。在申请头中传递一个蕴含base64编码的username:password字符串的 HTTPAuthorization头。因为base64很容易被解码，根本（Basic）认证应该只和其余平安机制一起应用，比方HTTPS/SSL。
  • API密钥。第三方应用程序通过公布一个密钥来取得应用API的许可，这个密钥可能有特定的权限或被限度在一个特定的域。密钥在每个申请中的HTTP头或查问字符串中被传递。
  • OAuth。在收回任何申请之前，通过向OAuth服务器发送一个客户ID和可能的客户机密，取得一个令牌。而后，OAuth令牌会随每个API申请一起发送，直到过期。
  • JSON Web Tokens (JWT)。数字签名的认证令牌在申请和响应头中平安地传输。JWT容许服务器对拜访权限进行编码，因而不须要调用数据库或其余受权零碎。

API身份验证将依据应用上下文而有所不同：

  • 在某些状况下，第三方应用程序被视为像任何其余具备特定权力和权限的登录用户。例如，一个地图API能够将两点之间的方向返回给调用的应用程序。它必须确认该应用程序是一个无效的客户端，但不须要检查用户凭证。
  • 在其余状况下，第三方应用程序正在申请用户的公有数据，如电子邮件内容。REST API必须辨认用户和他们的权力，但它可能不关怀哪个应用程序在调用API。

REST API安全性

RESTful API提供了另一种拜访和操作你的应用程序的路径。即便它不是一个引人注目的黑客指标，一个行为不良的客户端也可能每秒发送数以千计的申请，并使你的服务器解体。

安全性超出了本文的范畴，但常见的最佳实际包含：

  • 应用HTTPS。
  • 应用强壮的身份验证办法。
  • 应用CORS来限度客户端对特定域的调用。
  • 提供起码的性能，也就是不要创立不须要的DELETE选项。
  • 验证所有端点URL和body对象。
  • 防止在客户端JavaScript中裸露API令牌。
  • 阻止来自未知域名或IP地址的拜访。
  • 阻止意外的大型无效负载。
  • 思考速率限度，也就是应用同一API令牌或IP地址的申请被限度在每分钟N个以内。
  • 以适当的HTTP状态代码和缓存头进行响应。
  • 记录申请并考察失败状况。

多个申请和不必要的数据

RESTful APIs受到其实现的限度。响应可能蕴含比你须要的更多的数据，或者须要进一步的申请来拜访所有数据。

思考一个RESTful API，它提供对作者和书籍数据的拜访。为了显示前10名畅销书的数据，客户端能够：

  • 申请按销售量数量订购的前10/book/的详细信息（最滞销的在前）。响应蕴含有每个作者ID的书籍列表。
  • 最多组成10个/author/{id}申请以获取每个作者的详细信息。

这被称为N+1问题；必须为父申请中的每个后果提出N个API申请。

为了防止不必要的大的响应，能够调整API使作者的细节是可选的。例如，?author_details=full。API作者须要满足的选项的数量可能会变得令人困惑。

GraphQL是否更好？

REST的难题导致Facebook创立了GraphQL--一种网络服务查询语言。把它看作是网络服务的SQL：一个繁多的申请定义了你所须要的数据以及你心愿它如何返回。

GraphQL解决了RESTful APIs带来的一些挑战，只管它引入了其余挑战。例如，很难对GraphQL响应进行缓存。

你的客户不太可能有与Facebook相似的问题，所以一旦RESTful API倒退到超出其理论限度时，GraphQL可能值得思考。

REST API链接和开发工具

有许多工具能够帮忙所有语言的RESTful API开发。值得注意的选项包含：

  • Swagger：帮忙设计、记录、模仿、测试和监控REST APIs的各种工具。
  • Postman：一个RESTful API测试应用程序。
  • Hoppscotch：一个开源的、基于web的Postman替代品。

还有大量的公共REST API，汇合了笑话、货币转换、天文编码、政府数据以及你能想到的每一个主题。许多是收费的，只管有些须要你注册一个API密钥或应用其余认证办法。分类列表包含：

  • Any API
  • API list
  • Public APIs
  • Google APIs Explorer

在实现你本人的网络服务之前，在你本人的我的项目中尝试应用一些RESTful API。或者思考追随Facebook、GitHub、Google和其余许多巨头的脚步，建设一个属于本人的RESTful API。

下一篇文章中，会翻译分享13个构建RESTful API的最佳实际，欢送关注。

以上就是全部内容，如果对你有所帮忙，欢送点赞珍藏转发~