服务端指南 | 良好的 API 设计指南
设计一套良好的 API 接口。
原文地址：服务端指南 | 良好的 API 设计指南
博客地址：blog.720ui.com/
版本号
为了解决这个版本不兼容问题，在设计 RESTful API 的一种实用的做法是使用版本号。一般情况下，我们会在 url 中保留版本号，并同时兼容多个版本。
【GET】 /v1/users/{user_id} // 版本 v1 的查询用户列表的 API 接口
【GET】 /v2/users/{user_id} // 版本 v2 的查询用户列表的 API 接口复制代码资源路径
【GET】 /v1/tags/{tag_id}复制代码/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}复制代码我们来看一个“添加用户的角色”的设计，其中“用户”是主资源，“角色”是子资源。
【POST】 /v1/users/{user_id}/roles/{role_id} // 添加用户的角色复制代码有的时候，当一个资源变化难以使用标准的 RESTful API 来命名，可以考虑使用一些特殊的 actions 命名。
/{resources}/{resource_id}/actions/{action}复制代码举个例子，“密码修改”这个接口的命名很难完全使用名词来构建路径，此时可以引入 action 命名。
【PUT】 /v1/users/{user_id}/password/actions/modify // 密码修改复制代码请求方式
这里，笔者使用“用户”的案例进行回顾通过 GET、 POST、 PUT、 PATCH、 DELETE 等方式对服务端的资源进行操作。
【GET】 /users # 查询用户信息列表
【GET】 /users/1001 # 查看某个用户信息
【POST】 /users # 新建用户信息
【PUT】 /users/1001 # 更新用户信息(全部字段)
【PATCH】 /users/1001 # 更新用户信息(部分字段)
【DELETE】 /users/1001 # 删除用户信息复制代码查询参数
RESTful API 接口应该提供参数，过滤返回结果。其中，offset 指定返回记录的开始位置。一般情况下，它会结合 limit 来做分页的查询，这里 limit 指定返回记录的数量。
【GET】 /{version}/{resources}/{resource_id}?offset=0&limit=20复制代码同时，orderby 可以用来排序，但仅支持单个字符的排序，如果存在多个字段排序，需要业务中扩展其他参数进行支持。
【GET】 /{version}/{resources}/{resource_id}?orderby={field} [asc|desc]复制代码为了更好地选择是否支持查询总数，我们可以使用 count 字段，count 表示返回数据是否包含总条数，它的默认值为 false。
【GET】 /{version}/{resources}/{resource_id}?count=[true|false]复制代码上面介绍的 offset、 limit、 orderby 是一些公共参数。此外，业务场景中还存在许多个性化的参数。我们来看一个例子。
【GET】 /v1/categorys/{category_id}/apps/{app_id}?enable=[1|0]&os_type={field}&device_ids={field,field,…}复制代码注意的是，不要过度设计，只返回用户需要的查询参数。此外，需要考虑是否对查询参数创建数据库索引以提高查询性能。
状态码
使用适合的状态码很重要，而不应该全部都返回状态码 200，或者随便乱使用。这里，列举笔者在实际开发过程中常用的一些状态码，以供参考。
| 状态码 | 描述 |
|---|---|
| 200 | 请求成功 |
| 201 | 创建成功 |
| 400 | 错误的请求 |
| 401 | 未验证 |
| 403 | 被拒绝 |
| 404 | 无法找到 |
| 409 | 资源冲突 |
| 500 | 服务器内部错误 |
异常响应
当 RESTful API 接口出现非 2xx 的 HTTP 错误码响应时，采用全局的异常结构响应信息。
HTTP/1.1 400 Bad Request
Content-Type: application/json
{"code": "INVALID_ARGUMENT","message": "{error message}","cause": "{cause message}","request_id": "01234567-89ab-cdef-0123-456789abcdef","host_id": "{server identity}","server_time": "2014-01-01T12:00:00Z"
}复制代码请求参数
在设计服务端的 RESTful API 的时候，我们还需要对请求参数进行限制说明。例如一个支持批量查询的接口，我们要考虑最大支持查询的数量。
【GET】 /v1/users/batch?user_ids=1001,1002 // 批量查询用户信息
参数说明
- user_ids: 用户ID串，最多允许 20 个。复制代码此外，在设计新增或修改接口时，我们还需要在文档中明确告诉调用者哪些参数是必填项，哪些是选填项，以及它们的边界值的限制。
【POST】 /v1/users // 创建用户信息
请求内容
{"username": "lgz", // 必填, 用户名称, max 10"realname": "梁桂钊", // 必填, 用户名称, max 10"password": "123456", // 必填, 用户密码, max 32"email": "lianggzone@163.com", // 选填, 电子邮箱, max 32"weixin": "LiangGzone", // 选填，微信账号, max 32"sex": 1 // 必填, 用户性别[1-男 2-女 99-未知]
}复制代码响应参数
【GET】 /{version}/{resources}/{resource_id} // 返回单个资源对象
【GET】 /{version}/{resources} // 返回资源对象的列表
【POST】 /{version}/{resources} // 返回新生成的资源对象
【PUT】 /{version}/{resources}/{resource_id} // 返回完整的资源对象
【PATCH】 /{version}/{resources}/{resource_id} // 返回完整的资源对象
【DELETE】 /{version}/{resources}/{resource_id} // 状态码 200，返回完整的资源对象。// 状态码 204，返回一个空文档复制代码HTTP/1.1 200 OK
{"id" : "01234567-89ab-cdef-0123-456789abcdef","name" : "example","created_time": 1496676420000,"updated_time": 1496676420000,...
}复制代码HTTP/1.1 200 OK
{"count":100,"items":[{"id" : "01234567-89ab-cdef-0123-456789abcdef","name" : "example","created_time": 1496676420000,"updated_time": 1496676420000,...},...]
}复制代码一个完整的案例
最后，我们使用一个完整的案例将前面介绍的知识整合起来。这里，使用“获取用户列表”的案例。
【GET】 /v1/users?[&keyword=xxx][&enable=1][&offset=0][&limit=20] 获取用户列表
功能说明：获取用户列表
请求方式：GET
参数说明
- keyword: 模糊查找的关键字。[选填]
- enable: 启用状态[1-启用 2-禁用]。[选填]
- offset: 获取位置偏移，从 0 开始。[选填]
- limit: 每次获取返回的条数，缺省为 20 条，最大不超过 100。 [选填]
响应内容
HTTP/1.1 200 OK
{"count":100,"items":[{"id" : "01234567-89ab-cdef-0123-456789abcdef","name" : "example","created_time": 1496676420000,"updated_time": 1496676420000,...},...]
}
失败响应
HTTP/1.1 403 UC/AUTH_DENIED
Content-Type: application/json
{"code": "INVALID_ARGUMENT","message": "{error message}","cause": "{cause message}","request_id": "01234567-89ab-cdef-0123-456789abcdef","host_id": "{server identity}","server_time": "2014-01-01T12:00:00Z"
}
错误代码
- 403 UC/AUTH_DENIED 授权受限复制代码服务端指南 | 良好的 API 设计指南相关推荐
- RESTful API 设计指南[转]
一种软件架构风格.设计风格,而不是标准,只是提供了一组设计原则和约束条件.它主要用于客户端和服务器交互类的软件.基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制. RESTful AP ...
- 组件接口(API)设计指南－文件夹
组件接口(API)设计指南-文件夹 组件接口(API)设计指南[1]-要考虑的问题 组件接口(API)设计指南[2]-类接口(class interface) 组件接口(API)设计指南[3]-托付( ...
- RESTful API 设计指南 (转)
RESTful API 设计指南 2016-02-23 ImportNew (点击上方公号,可快速关注) 作者:阮一峰 链接:http://www.ruanyifeng.com/blog/2014/0 ...
- RESTful API 设计指南
原文地址:http://www.ruanyifeng.com/blog/2014/05/restful_api.html RESTful API 设计指南 作者: 阮一峰 日期: 2014年5月22日 ...
- Android端+Java服务端+servlet+MySQL二手商城设计
项目地址: Android端+Java服务端+servlet+MySQL二手商城设计.zip-Android文档类资源-CSDN下载 项目简介及内容截图如下: 本系统适用于计算机专业作为期末课程设计. ...
- HTTP API 设计指南（基础部分）
为了保证持续和及时的更新,强烈推荐在我的Github上关注该项目,欢迎各位star/fork或者帮助翻译 前言 这篇指南介绍描述了 HTTP+JSON API 的一种设计模式,最初摘录整理自 Hero ...
- Google API 设计指南 - 前言
原文地址:https://cloud.google.com/apis... Copyright: Creative Commons Attribution 3.0 License Current Ve ...
- google api设计指南-简介
简介 这是联网 API 的通用设计指南.它自 2014 年起在 Google 内部使用,是 Google 在设计 Cloud API 和其他 Google API 时遵循的指南.此设计指南在此处共享, ...
- Google API 设计指南－设计模式
翻译自 API Design Guide - Design Patterns 空响应体 标准的 Delete 方法 必须(must) 返回 google.protobuf.Empty 来实现全局一致性 ...
最新文章
- CodeGen用户定义的扩展令牌
- AI超算“攒机”时代到来：为降低算力成本，这家公司牵头开放硬件标准
- oracle列,oracle列合并
- android编译.a文件,Android 7.1源码编译导入AS完整教程
- C语言中（）和【】的区别？
- Android典型界面设计(8) ——ViewPager+PagerSlidingTabStrip实现双导航
- 使用前端框架Foundation 4来帮助简化响应式设计开发
- go语言快速刷《程序员面试金典》（3）
- Ubuntu下绘图软件krita64位无中文问题
- java数据结构之选择排序
- 采集浏览器访问某网站时产生的流量，并保存为pcap文件
- 落魄前端，整理给自己的前端知识体系复习大纲（下篇）
- 36. BOM (2)
- Pytorch和Torchvision版本对应
- 怎么对接口做幂等性操作？
- hitool java_海思HiTool-STB-5.0.27最新版工具
- Django搭建个人博客之制作app并配置相关环境
- 移动端关于手机横屏时样式修改
- 边缘计算在物联网领域的发展前景
- Poco C++类库使用说明