文章部分内容转自：https://www.colabug.com/2017/0627/228298/

REST 是一种软件架构风格，如果你们的接口是 REST 接口，那么就可被认为你们的的接口是 RESTful 的，英文名词和形容词的区别。

REST 接口是围绕“资源”展开的，利用 HTTP 的协议。其实 REST 本也可以和 HTTP 无关，但是现在大家普遍的使用 REST 都是依托于HTTP协议。

URL 语法

RFC 3986
定义了通用的URI语法：

1
URI = scheme “://” authority “/” path [ “?” query ][ “#” fragment ]
  • scheme: 指底层用的协议，如 http、https、ftp
  • host: 服务器的 IP 地址或者域名
  • port: 端口，http 中默认 80
  • path: 访问资源的路径，就是咱们各种 web 框架中定义的 route 路由
  • query: 为发送给服务器的参数
  • fragment: 锚点，定位到页面的资源，锚点为资源id

RESTful API 设计

资源路径

对于资源的定义，即 URL 的定义，是最重要的；想要设计出优雅的、易读的 REST 接口，其实还是很不容易的。

URL 中不能有动词

在 RESTful 架构中，每个网址代表的是一种资源，所以网址中不能有动词，只能有名词，动词由 HTTP 的 get、post、put、delete 四种方法来表示。

URL 结尾不应该包含斜杠 /

这是作为 URL 路径中处理中最重要的规则之一，正斜杠 / 不会增加语义值，且可能导致混淆。REST API 不允许一个尾部的斜杠，不应该将它们包含在提供给客户端的链接的结尾处。

许多Web组件和框架将平等对待以下两个URI：

1
2
http://api.canvas.com/shapes/
http://api.canvas.com/shapes

但是，实际上URI中的每个字符都会计入资源的唯一身份的识别中。

两个不同的 URI 映射到两个不同的资源。如果 URI 不同，那么资源也是如此，反之亦然。因此，REST API 必须生成和传递精确的 URI，不能容忍任何的客户端尝试不精确的资源定位。

有些 API 碰到这种情况，可能设计为让客户端重定向到相应没有尾斜杠的 URI（也有可能会返回301 – 用来资源重定向）。

正斜杠分隔符 / 必须用来指示层级关系

url 的路径中的正斜杠 / 字符用于指示资源之间的层次关系。

例如：

1
2
3
4
5
http://api.user.com/schools/grades/classes/boys
– 学校中所有的男生

http://api.college.com/students/3248234/courses
– 检索id为3248234的学生学习的所有课程的清单。

应该使用连字符 - 来提高 URL 的可读性，而不是使用下划线 _

为了使 URL 容易让人们理解，请使用连字符 _ 字符来提高长路径中名称的可读性。

一些文本查看器为了区分强调 URI，常常会在 URI 下加上下划线。这样下划线 _ 字符可能被文本查看器中默认的下划线部分地遮蔽或完全隐藏。

为避免这种混淆，请使用连字符 - 而不是下划线

URL路径中首选小写字母

RFC 3986 将 URI 定义为区分大小写，但 scheme 和 host components 除外。

URL路径名词均为复数

为了保证 url 格式的一致性，建议使用复数形式。

RESTful API对资源的操作

对于 REST api 资源的操作，由 HTTP 动词表示

CURD 操作

  • GET：获取资源
  • POST：新建资源
  • PUT：在服务器更新资源（向客户端提供改变后的所有资源）
  • PATCH：在服务器更新资源（向客户端提供改变的属性，一般不用，用 PUT）
  • DELETE：删除资源

资源过滤

在获取资源的时候，有可能需要获取某些“过滤”后的资源，例如指定前10行数据

1
http://api.user.com/schools/grades/classes/boys?page=1&page-size=10

返回状态码推荐标准HTTP状态码

有很多服务器将返回状态码一直设为 200，然后在返回 body 里面自定义一些状态码来表示服务器返回结果的状态码。由于 REST api 是直接使用的 HTTP 协议，所以它的状态码也要尽量使用 HTTP 协议的状态码。

  • 200 OK 服务器返回用户请求的数据，该操作是幂等的
  • 201 CREATED 新建或者修改数据成功
  • 204 NOT CONTENT 删除数据成功
  • 400 BAD REQUEST 用户发出的请求有问题，该操作是幂等的
  • 401 Unauthoried 表示用户没有认证，无法进行操作
  • 403 Forbidden 用户访问是被禁止的
  • 422 Unprocesable Entity 当创建一个对象时，发生一个验证错误
  • 500 INTERNAL SERVER ERROR 服务器内部错误，用户将无法判断发出的请求是否成功
  • 503 Service Unavailable 服务不可用状态，多半是因为服务器问题，例如CPU占用率大，等等

更多的可以参考维基百科，或者这篇博客。

具体情形具体分析

REST API 是一个非常宏大的问题，只能说具体情形具体分析。

一个方法是参考现有的代码或后端框架等等，如 Django REST Framework 提供的教程就是一个带有简单权限管理的 Snippet。

还有一个方法就是在 Stack Overflow 上搜索你的行为 + REST API 或 http status code，会出现大量的结果供参考，如 logout http status code 会搜到关于注销应当返回什么，返回的状态码是否有意义这类问题。

登录和登出

  1. 登录和登出应该使用不同的路径，如 /login 和 /logout。Stack Overflow
  2. 登录和登出都应该使用 POST 方法，这是为了防浏览器预加载，以及防止搜索引擎的爬虫。Stack Overflow
  3. 登出操作完成后应当返回一个 HTTP 204 No Content 报文，虽然这对大部分前端都没什么用，但是说不定真的有人需要用接收报文作时间戳什么的。Stack Overflow

重置密码

Stack Overflow 中给出了相当多的方案：