1. restful风格介绍
- 目的: 了解什么是restful风格
- restful: 一种软件架构风格、设计风格,而不是标准
- 好处: 方便团队协作
2. restful设计风格
- 目的: 知道常见的restful的设计风格
- 设计风格:
- 1, 域名: api需要部署在专用域名下,或者主域名
- 2, 版本: 不同的api版本通过路径或者请求头的形式表示
- 3, 路径: 不要有动词, 尽量使用名词
- 4, http动词: 严格区分get,post,put,delete的作用
- 5, 过滤信息: api应该提供参数,返回结果
- 6, 状态码: 严格返回对应的状态码,200,201,204,400,401,403,404,500
- 7, 错误处理: 当请求出错的时候, 尽量返回提示信息
- 8, 返回值: 尽量返回json而不是xml
- ….
- 域名
-
API需要部署在专用域名或者主域名下
https://api.example.com # 专用域名
https://example.org/api/ # 主域名
- 版本(Versioning)
-
不同的API版本通过路径或者请求头的形式表示
http://www.example.com/app/1.0/foo http://www.example.com/app/1.1/foo http://www.example.com/app/2.0/foo
- 路径(Endpoint)
-
不要有动词, 尽量使用名词
GET /products :将返回所有产品清单 POST /products :将产品新建到集合 GET /products/4 :将获取产品 4 PATCH(或)PUT /products/4 :将更新产品 4
- HTTP动词
-
严格区分get,post,put,delete的作用
-
常用HTTP动词(括号里是对应的SQL命令):
- GET(SELECT):从服务器取出资源(一项或多项)。
- POST(CREATE):在服务器新建一个资源。
- PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
- DELETE(DELETE):从服务器删除资源。
- 过滤信息(Filtering)
-
API应该提供参数,过滤返回结果
-
下面是一些常见的参数。
?limit=10:指定返回记录的数量 ?offset=10:指定返回记录的开始位置。 ?page=2&per_page=100:指定第几页,以及每页的记录数。 ?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。 ?animal_type_id=1:指定筛选条件
- 状态码(Status Codes)
-
严格返回对应的状态码:200,201,204,400,401,403,404,500
-
服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词)。
- 200 OK - [GET]:服务器成功返回用户请求的数据
- 201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
- 204 NO CONTENT - [DELETE]:用户删除数据成功。
- 400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作
- 401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
- 403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
- 404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作等。
- 500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
- 错误处理(Error handling)
-
当请求出错时,尽量返回提示信息
-
如果状态码是4xx,服务器就应该向用户返回出错信息。一般来说,返回的信息中将error作为键名,出错信息作为键值即可。
{ error: "Invalid API key" }
- 返回结果
-
返回的结果尽量符合规范
-
针对不同操作,服务器向用户返回的结果应该符合以下规范。
- GET /collection:返回资源对象的列表(数组)
- GET /collection/resource:返回单个资源对象
- POST /collection:返回新生成的资源对象
- PUT /collection/resource:返回完整的资源对象
- PATCH /collection/resource:返回完整的资源对象
- DELETE /collection/resource:返回一个空文档
- 其他
- 服务器返回的数据格式,应该尽量使用JSON,避免使用XML。