Skip to main content

RESTfulAPI接口设计标准及规范

Browser URL规范​

基本规范​

  • 不允许出现没有意义的下 URL

  • 只能允许英文字母（az，全小写）、数字（09），英文连接符(-)

  • https://展开的层级目录内容中不允许出现“丨”、下划线“_”、多斜杠字符“//”、“+”、“#”（除特殊情况比如开发人员使用#锚点定位）

  • 层次命名不要超过3个单词 正确示例：https://www.example.com/first/second/third.html

    错误示例：https://www.example.com/first/second/third/forth.html

  • 总 URL 长度不要超过 72 个字符

  • 不允许存在多余参数或空格

  • URL 目录命名需要避免歧义，通常使用英文全称，英文无法满足时使用直译

  • URL 中参数尽可能少，不要超过 3 个，一般 2~3 即可

  • URL应该呈现一个降级的次序（例如：域名/类型/分类/标题）

  • 如果是内容资源URL，不允许以参数的方法显示 例如：http://www.uxuexi.cn/user.html?userId=123 需要改成 http://www.uxuexi.cn/user/123.html

类型设置

RESTful​

URI 规范​

  1. /不应该出现在 URL 末尾
  2. RESTful API 对 URI 资源的定义具有唯一性，一个资源对应唯一的一个地址 如果访问到末尾含 /的地址，服务端应该 301 到没有 /的地址
  3. 路径中使用中横线 -代替下划线进行单词分割
  4. 参数名称使用下划线 _进行连接
  5. 路径中统一使用小写字母
  6. 参数列表进行 encode

API 演进​

版本。常见三种方式：

  1. 在 uri 中放版本信息：GET /v1/users/1 // 使用的最多
  2. Accept Header：Accept: application/json+v1
  3. 自定义 Header：X-Api-Version: 1

资源集合 vs 单个资源​

资源集合：

/zoos //所有动物园
/zoos/1/animals //id为1的动物园中的所有动物

单个资源：

/zoos/1 //id为1的动物园
/zoos/1;2;3 //id为1，2，3的动物园

避免层级过深的URI​

/在 url 中用于表达层级，用于按实体关联关系进行对象导航，一般根据 id 导航

GET /animals?zoo=1&area=3

对Composite资源的访问​

服务器端的组合实体必须在uri中通过父实体的id导航访问

组合体不是 first-class 的实体，其生命周期完全依赖父实体，无法独立存在，实现上通常是对数据库某些表的抽象

// User 
// Address 对 User 某些字段的抽象
GET /user/1/addresses

Request​

GET 查询

GET /zoos
GET /zoos/1
GET /zoos/1/employees

POST 创建单个资源

POST /animals  //新增动物
POST /zoos/1/employees //为id为1的动物园雇佣员工

PUT 全量更新单个资源

PATCH 部分更新单个资源

PUT /animals/1
PUT /zoos/1

DELETE 删除

DELETE /zoos/1/employees/2
DELETE /zoos/1/employees/2;4;5
DELETE /zoos/1/animals  //删除id为1的动物园内的所有动物

复杂查询​

.示例备注
过滤条件?type=1&age=16允许一定的uri冗余，如 /zoos/1与 /zoos?id=1
排序?sort=age,desc
投影?whitelist=id,name,email
分页?limit=10&offset=3
Last updated on by hanami