Restful

本文为阅读阮一峰老师的博客所作的总结

REST： Representational State Transfer. 表现层状态转换?

1. 资源 Resources
REST的主语，即资源表现层状态转换
资源就是网络上的某一具体信息，比如文本、图片等等。用户所请求的一个具体信息。
一个资源对应一个URI（统一资源标识符）。
2. 表现层 Representational
资源的表现形式，一个资源可以表现为txt或者html或者json等很多种方式，但是URI只代表资源实体，标识资源的位置，不代表其表现形式。
**资源的表现形式，由HTTP请求头信息中的Accept和响应头的Content-Type指定。
3. 状态转换 State Transfer
客户端通过HTTP协议，来实现表现层的状态转换。

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

RESTful API 设计指南

1. 使用HTTPS协议
2. 域名：
    - API应部署在专用域名之下： https://api.example.com
3. 版本号防止URL里： https://api.example.com/v1/
4. 路径：一个网址代表一个资源，不能有动词只能用名词，名词一般要与数据库的表格对应
    - https://api.example.com/v1/zoos
    - https://api.example.com/v1/animals
5. HTTP动词：
    - GET (select)： 获取资源
    - POST（CREATE): 新建资源or更新资源
    - DELETE (DELETE): 删除资源
6. 过滤信息：
    - ?limit=10
    - ?offset=10
    - ?page=2&per_page=100
    - ?sortby=name&order=asc
    - ?animal_type_id=1
7. 状态码：
    - 200 ok - [get]: 服务器成功返回用户请求
    - 201 created - [post/put] : 新建or更新数据成功
    - 202 accepted - [*] : 请求进入后台排队，异步任务
    - 204 no content -[DELETE]: 用户请求数据成功
    - 400 invalid request - [post/put]: 用户请求错误，服务器没有进行数据新建or修改操作，该操作幂等
    - 401 unauthorized  - [*]: 用户无权限
    - 403 forbidden - [*]: 有权限但访问是被禁止的
    - 404 not found - [*]: 用户请求的数据不存在
    - 406 not acceptable - [get]: 用户请求格式不可得，用户请求json但是只有xml
    - 410 gone - [get] : 请求的资源被永久删除
    - 422 unprocesable entity - [post]: 创建对象时发生验证错误
    - 500 internal server error -[*]: 服务器发生错误
8. 错误处理：状态码是4xx应向用户返回出错信息
    - { error_name: error_info}
9. Hypermedia API: 返回结果提供链接，连向其他api
10. 服务器返回数据格式尽量使用json

RESTful api 实践

URL 设计
- 动词＋宾语：动词是HTTP的方法，get、post、delete，如 get /articles
- 宾语是名词，使用复数
- 避免多级URL应该使用HTTP方法的参数。如 get /authors/l2/categories/2应为 get /authors/l2?categories=2, GET /articles/published应为GET /articles?published=true
状态码要精确
- api用不到1xx和301永久重定向、302临时重定向。301和302是应用级别返回，浏览器会跳转，api级别可以不考虑这种情况
- api主要用303 see other，表示参考另一个URL。303不会导致浏览器跳转，用户决定下一步怎么做
服务器回应要为json，响应头的Conten-Type为application/json, 请求头要在Accept里设置为application/json