RESTful API 是一种基于 REST（Representational State Transfer）原则设计的公共接口，旨在提高 Web 应用程序的交互性和可重用性。RESTful API 可以被 HTTP 协议调用，每个资源通过一个 URI（Uniform Resource Identifier）来定义，该 URI 的操作则在不同的 HTTP 请求方法中进行。本文将详细探讨调用 RESTful API 时应遵循的规范与实践。
1. 调用规范
1.1. URI 设计
在 URI 设计方面，应该将每个资源定义为一个独立的 URI。URI 应该只包含名词和不包含动词。例如：
GET /users // 获取用户列表 GET /users/123 // 获取 ID 为 123 的用户信息 POST /users // 创建一个新用户 PUT /users/123 // 更新 ID 为 123 的用户信息 DELETE /users/123 // 删除 ID 为 123 的用户信息
另外，URI 应该使用小写字母，并用连字符分隔单词。例如：
GET /my-books // 获取我的书籍列表
1.2. HTTP 方法
在 HTTP 方法方面，应该根据所执行的操作来选择正确的方法。例如：
- GET：用于获取资源的信息，不应对服务器端数据做任何更改。
- POST：用于创建新资源。
- PUT：用于对现有资源进行更新，客户端应对整个资源进行更新。
- DELETE：用于删除资源。
- PATCH：用于对资源进行部分更新。
1.3. HTTP 状态码
在 HTTP 状态码方面，应该使用正确的状态码来表示请求的成功或失败。
- 2xx：请求成功，如 200 OK 表示请求成功。
- 3xx：重定向，如 301 Moved Permanently 表示请求的 URI 已被永久重定向到新的 URI。
- 4xx：客户端错误，如 404 Not Found 表示请求的资源不存在。
- 5xx：服务器错误，如 500 Internal Server Error 表示服务器端发生错误。
1.4. 错误处理
在错误处理方面，应该对服务器端返回的错误信息进行封装，以提高客户端对错误信息的处理能力。例如：
-- -------------------- ---- -------
-------- --- --- -----
------------- ----------------
-
-------- -
------- ------
---------- ---------- -------- --- --- -------
---------- -
------ ------------
-
-
-2. 调用实践
2.1. 鉴权
在调用 RESTful API 时，应进行鉴权，以确保请求的合法性。常见的鉴权方式有：
- HTTP Basic 鉴权
- OAuth2 鉴权
HTTP Basic 鉴权是指在请求头中添加 Authorization 字段，使用 Base64 对用户名和密码进行编码，并在后面添加 Basic 前缀。例如：
Authorization: Basic Base64(username:password)
OAuth2 鉴权是指通过授权访问令牌来确认请求是否合法的机制。它与 HTTP Basic 鉴权相似，但使用不同的数据包和访问令牌。例如：
Authorization: Bearer access_token
2.2. 异步调用
在调用 RESTful API 时，应尽可能使用异步调用，以避免服务器端的阻塞。异步调用可以采用 Promise、回调函数或事件处理程序等方式实现。
例如，在使用 Axios 客户端库进行异步调用时，可以使用 Promise 实现：
axios.get('/user')
.then(function (response) {
console.log(response);
})
.catch(function (error) {
console.log(error);
});2.3. 客户端库
在调用 RESTful API 时，应尽可能使用客户端库，以方便进行鉴权、异常处理和代码重用。常见的客户端库有：
- Axios
- jQuery AJAX
- AngularJS $http
例如，在使用 Axios 客户端库进行调用时，可以如下所示：
-- -------------------- ---- -------
-- -- ----- -
------ ----- ---- --------
-- ------
---------------------- - ------------------------
---------------------- - -
--------------- ------------------
--
-- -- ------- ---
-------------------
-------------- ---------- -
---------------------------
--
--------------- ------- -
-------------------
---3. 总结
本文详细介绍了调用 RESTful API 时应遵循的规范与实践。遵循这些规范与实践可以提高 API 的可用性和可重用性，减少客户端开发人员的工作量。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6495665b48841e989429785f