RESTful 风格 API 设计规范

1. 配置单独域名

建议将API部署到专用域名下, 如: https://api.example.com
如果不需要考虑扩展可以将API当做一个模块来开发 https://www.example.com/api

2. 将版本放入url中

建议将版本放入url地址中, 如: https://api.example.com/v1.1

3. 使用 http 方法进行对应的操作:

GET           获取资源
POST          新建资源
DELETE        删除资源
PUT           更新资源

4. 提供参数

API应该提供参数, 比如分页, 在PC端和移动端可能是不一样的 比如PC端一页 30 条数据, 而移动端是 一页 10 条数据

https://api.example.com/v1?offset=30
https://api.example.com/v1?offset=10

5. 接口应该返回 JSON格式 的 状态码 和 提示信息

{
    "status "  :  "200",
    "message" : "操作成功"
}

6. 错误处理

如果后端代码可能执行报错, 应该 try..catch 让代码正常执行 catch 并返回信息

{
    error: "您访问的页面不存在"
}

7. 返回结果, 根据不同的操作返回不同结果(JSON格式)

• 返回多个对象信息 GET https://api.example.com/v1/users 返回用户列表

[
    {"name" : "Alex", "age": "18"},
    {"name" : "Tom", "age": "20"},
    {"name" : "Jason", "age": "22"}
]

• 返回单个信息 GET https://api.example.com/v1/user/1 返回id为1的用户信息

{"name" : "Alex", "age": "18"}

• 删除某个对象信息 DELETE https://api.example.com/v1/user/1 返回提示信息

{
    "status "  :  "200",
    "message" : "操作成功"
}

• 创建一个对象信息 POST https://api.example.com/v1/users 返回提示信息

{
    "status "  :  "403",
    "message" : "操作失败"
}

• 修改一个对象信息 PUT 或 PATCH https://api.example.com/v1/user/1 返回提示信息

{
    "status "  :  "200",
    "message" : "操作成功"
}

8. 编写 API 使用文档

• 请求地址及参数

  
  Api

• 描述说明

  
  params description

最后

文明浏览,不喜勿喷,谢谢!! ^_^