REST API 设计最佳实践

Best practices for REST API design - Stack Overflow

REST API 是最常见的 Web 服务类型之一。浏览器、应用程序等各种客户端 都可以通过 REST API与服务器通信。

正确设计 REST API 非常重要, 我们要考虑 REST API 的安全性、性能和易用性。

什么是 REST API

REST API 是一种应用程序编程接口, 它符合特定的体系结构约束,如无状态通信和可缓存数据。它不是协议或标准

虽然 REST API 可以通过多种通信协议进行访问,但最常见的是通过 HTTPS 。

以下准则适用于将通过 Internet 调用的 REST API 端点。

注意:对于通过互联网调用的 REST API,您需要遵循 REST API 身份验证的最佳实践。

使用 JSON 作为输入和响应

REST API 应以 JSON 作为数据传输标准:

  • 接受 JSON 作为请求负载
  • 通过 JSON 发送响应。

JSON 是传输数据的标准,无论是客户端还是服务器端,使用JSON都很方便。

表单比较适合发送文件。但对于文本和数字,我们可以直接在客户端从中获取JSON传输。这样最直接。

在返回JSON时,应该设置响应标头,`Content-Type: application/json`。不过很多库会自动替我们设置这个标头。

在路径中使用名词而不是动词

我们不应该在端点路径中使用动词。相反,应该使用相关实体的名词,作为路径名。

这是因为我们的 HTTP 请求方法已经具有动词。在我们的 API 终结点路径中使用动词是没有用的。它不传达任何新信息,只是显得冗长,而且,所选动词可能因开发人员的心血来潮而异。例如,有人用“get”,有人用“retrieve”。

所以最好让HTTP GET动词告诉我们和端点的作用。

最常用的方法包括 GET、POST、PUT 和 DELETE。

  • GET 检索资源。
  • POST 将新数据提交到服务器。
  • PUT 会更新现有数据。
  • DELETE 删除数据。

动词映射到 CRUD 操作。比如:

  • GET /articles 获得取文章列表
  • GET /articles/:id 获得某篇文章
  • POST /articles 创建新文章
  • PUT /articles/:id 修改某篇文章
  • DELETE /articles/:id 删除某篇文章

在路径中使用资源嵌套

在实际中,一个资源可能包含其它资源,比如一篇文章可能包含多个评论。我们要设计合理的路径来表示这种嵌套。

注意:REST API 路径中的资源嵌套最好不要照搬数据库的表结构,以免后台数据结构的泄露。

比如,GET /articles/:articleId/comments 得到某篇文章的所有评论。

然而,这种嵌套可能有很多层,尤其在二三层之后,这种结构就会变得很笨拙。这时候,就可以通过返回对象的URL 来终止这种嵌套。

比如:你想得到某篇文章的某个评论的作者,与其返回某个 articleId 中大而全的结构,不如在 /articles/:articleId/comments/:commentId/author 中直接返回 URI "author": "/users/:userId"

这个,客户端在拿到地址之后,可以再根据接口,拉取更详细的信息。避免一次查询过于臃肿。

优雅地处理错误 - 返回有效的信息

API 出错可能有多种情况,但我们可以把出错分为两大类:

  • HTTP 协议级出错
  • 上层应用逻辑出错

周全考虑,我们应该返回 HTTP 返回码和应用逻辑状态码。HTTP 返回码通常是标准的,而应用逻辑状态码需要我们自己约定。

使用 HTTP 标准返回码

常见的 HTTP 状态码包括:

  • 200 OK -  HTTP 请求正常
  • 400 BAD REQUEST  - 请求的参数格式错误
  • 401 UNAUTHORIZE - 认证未通过(比如用户名密码错,导致不能通过认证)
  • 403 FORBBIDEN - 没有授权
  • 404 NOT FOUND - 找不到资源,这个有时候会被电信运营商劫持
  • 500 INTERNAL SERVER ERROR - 通用的服务器内部错误
  • 502 BAD GATEWAY - 上游服务出错
  • 503 SERVICE UNAVAILABLE - 服务不可用

还应加上应用状态信息

除了认真返回 HTTP 状态码之外,我们还应该在返回内容中增加 err 部分,添加更细致的返回/出错状态信息。

比如,数据库连接失败:

{
  "status": 502,
  "err": {
    "code": 502001,
    "msg": "后台数据库连接失败"
  },
  "data": {
  }
}

如果正常:

{
  "status": 200,
  "err": {
    "code": 0,
    "msg": "",
  },
  "data": {
    正常的返回数据
  }

支持分页、筛选、排序

REST API 背后的数据可能非常大,我们需要提效分页和筛选功能,以提高效率。

比如:/employees?lastName=Smith&age=30&page=2

或者:/aritcles?sort=+author, -datepublished  加号、减号代表排序顺序

加强安全

  • 使用 TLS/SSL
  • 贯彻最小特权原则 - 普通用户应该无法访问其他用户的信息,不能访问管理员的数据。不同角色的权限要有明确的控制。

使用缓存提高性能

使用缓存有助于提高性能,因为不用每次都查询数据库了。当然,缓存有可能过时,导致调试了生产时的一些问题。使用时要特别小心。

缓存的解决方案有 Redis, Memcache 等。

注意应在标头中使用 Cache-Control 来为使用者提供更详细的指引。

API 版本控制

API 接口改动可能会引起客户端的更改,为了提供更好的兼容性,我们应该提供版本控制。

常见的做法是在 API 路径开头提供 /v1 /v2 这样的前缀来表示API的版本。 /employees?lastName=Smith&age/employees?lastName=Smith&age=30

你可能感兴趣的:(js,javascript)