RESTful API 接口设计整理

安全

  • 总是使用 TLS,非 TLS 不重定向,直接返回调用错误 403
  • 无状态认证机制使用 JWT

URI 的定义

URI 是对一个资源的指向,同一个资源必须使用同一个 URI,不同的资源使用不同的 URI。资源的处理使用动词,GET(查询)、POST(创建)、PUT(全局更新)、PATCH(局部更新)、DELETE(删除)。

请求方式动词 URI 注解
GET /users 显示所有用户列表的页面
GET /users/{id} 显示用户个人信息的页面
GET /users/create 创建用户的页面
POST /users 创建用户
GET /users/{id}/edit 编辑用户个人资料的页面
PATCH /users/{id} 更新用户
DELETE /users/{id} 删除用户
  • 使用复数来命名资源,即使资源绝对只有一个
  • 路径、参数均要小写
  • 路径要为名词,不要为动词
  • 路径如果需要多个单词,可以用减号隔开
  • 路径中的 /,用于表示资源之间的层次关系
  • 参数名称如果需要多个单词,可以用下划线隔开
  • URI 末尾不要包含斜杠
  • URI 中不包含文件的扩展名

查询参数

排序

字段前缀”-“表示降序

?sort=-create_time,id

过滤

不返回 content,keywords 信息

?fields=content,keywords

版本

三种方式

  • HTTP Accepts 头
  • URL
  • URL 主版本、HTTP 次版本

Request Headers

Content-Typeapplication/json,否则响应返回 415 Unsupported Media Type

状态码

客户端请求错误使用 400 系列状态码,服务端响应错误使用 500 系列状态码。

状态码 注解
200 请求资源成功
201 同步处理资源的新建或修改成功,返回包含新资源地址的 Location 头
202 资源的新建或修改进入异步
204 不返回响应主体的成功请求的响应,例如,资源删除成功
206 返回了部分资源
400 请求格式、参数缺失或者错误
401 没有权限
403 访问被禁止
404 资源不存在
405 所请求的 HTTP 方法不允许当前认证用户访问
406 请求的数据格式不存在
410 资源被永久删除
415 请求的媒体类型错误
422 请求理解成功,但是参数验证错误
429 请求频率超限
500 服务器内部错误

响应主体

  • 全局唯一的小写的 8-4-4-4-12 格式的 UUID,如果嵌套资源,嵌套的资源内依然需要具备一个这样的 UUUID
  • 资源的创建时间
  • 资源的最后更新时间
  • 下一步可用的 URL,客户端不需要关心
  • 修改或者创建后,尽量完整的资源详细数据

错误

  • 唯一的错误码
  • 错误信息
  • 详细的细节描述

自定义 Headers

关于调用频率的一个例子:

X-Rate-Limit-Limit:当前时间段内允许的最多请求次数
X-Rate-Limit-Remaining:当前时间段内剩余的请求次数
X-Rate-Limit-Reset:还有多少秒,请求次数限制会被重置

目前大部分使用“X-”前缀来区分自定义与非自定义的 HTTP 头,RFC 6848 已经开始废弃这种做法,但目前依然可用。

缓存

  • ETag
  • Last-Modified

API WIKI 文档要点

  • API 文档要与 API 同步更新
  • 文档格式的三个部分:请求方式、路径;参数名称、参数类型、参数注解;完整的响应示例

相关资料

来自HeroKu的HTTP API 设计指南(中文版)

深入理解 RESTful Api 架构

理解RESTFul架构

[译] REST API URI 设计的七准则

RESTful API 设计参考文献列表

RESTful API 设计与工程实践

RESTful API 设计指南

知识共享许可协议
本作品采用知识共享署名-非商业性使用-禁止演绎 4.0 国际许可协议进行许可。
随喜
支付宝随喜
微信随喜

你这完全不是RESTful API啊

跨域上面的OPTIONS方法带json数据传过去始终不成功,POST却可以。搞的头大