@wrlqwe
2016-02-28T13:37:34.000000Z
字数 2633
阅读 1214
RESTful API 设计
开发 软件设计
简介
Representational State Transfer简称REST，是一种软件架构风格，符合REST的设计称为RESTful。
RESTful系统一般使用HTTP(S)协议，通过GET、POST、PUT、DELETE等标准动词处理用URI标识的网络资源。
REST是Roy Fielding博士于2000年在他的博士论文中提出来的，RESTful在能完成传统API设计的功能的同时，带来了一些传统API设计中没有的优点：
1. 更为便利的交互，更好的兼容性。
2. 借助HTTP标准交互方式，逻辑更加清晰。
3. 高效利用缓存来提高响应速度。
4. 通讯本身的无状态性可以减少服务器的耦合，提高扩展性。
5. 更小的软件依赖。
要求
要实现RESTful，必须要满足如下要求：
1. 客户端-服务器模型
客户端不关心服务端的数据存储，服务端不关心客户端的表现形式，只要API没有变，二者相互独立，各自演进。
2. 无状态
服务端不保存任何客户端的连接信息，每一个request包含了所有服务端需要的信息。
3. 可缓存
请求Response必须显式或隐式地指出它们是否可被缓存，以便客户端对连接进行重用，提升性能。
4. 层次化系统
客户端所请求的server可能不是最终的服务端，服务端可以通过提供共享缓存的方式来实现负载均衡。
5. 统一接口（Uniform interface不知怎么翻译）
统一接口是设计任何RESTful service的基础，统一接口简化并解耦了架构，使各模块独立发展，它有4点要求：
1. 标识资源
在请求中标识单个resource，一般用URI标识，它并不一定是服务器的真实资源。
2. 通过资源的表现层操作资源
resource呈现出来的形式就是representation，客户端取到资源的representation时，就拥有了足够的数据来修改resource。
3. 自描述的信息
每条消息包含了足够的信息来处理它。
4.Hypermedia as the engine of application state (HATEOAS)
Clients make state transitions only through actions that are dynamically identified within hypermedia by the server (e.g., by hyperlinks within hypertext). Except for simple fixed entry points to the application, a client does not assume that any particular action is available for any particular resources beyond those described in representations previously received from the server.
Web Service里的应用
应用了REST设计的Service API就是RESTful，基于HTTP协议的RESTful API由以下几个方面来定义：
1. 类似 http://example.com/resources/ 的 简短URI。
2. 接收返回符合MIME类型的数据。
3. resource操作借用标准HTTP Methods(OPTIONS, GET, PUT, POST, DELETE, etc.)
4. 应用http status code 表示资源操作的结果。
下表列出了在实现RESTful API时HTTP请求方法的典型用途。
| 资源 | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| 一组资源的URI，比如http://example.com/resources/ | 列出URI，以及该资源组中每个资源的详细信息（后者可选）。 | 使用给定的一组资源替换当前整组资源。 | 在本组资源中创建/追加一个新的资源。该操作往往返回新资源的URL。 | 删除整组资源。 |
| 单个资源的URI，比如http://example.com/resources/142 | 获取指定的资源的详细信息，格式可以自选一个合适的网络媒体类型（比如：XML、JSON等） | 替换/创建指定的资源。并将其追加到相应的资源组中。 | 把指定的资源当做一个资源组，并在其下创建/追加一个新的元素，使其隶属于当前资源。 | 删除指定的元素。 |
关于http verbs
- GET（SELECT）：从服务器取出资源（一项或多项）。
- POST（CREATE）：在服务器新建一个资源。
- PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
- PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
- DELETE（DELETE）：从服务器删除资源。
还有两个不常用的： - HEAD：获取资源的元数据。
- OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。
HTTP Status Code
- 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
- 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
- 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
- 204 NO CONTENT - [DELETE]：用户删除数据成功。
- 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
- 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
- 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
- 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
- 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
- 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
- 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
- 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
疑问
- Filter请求，阮一峰的文章里推荐参数放在query params里，这样更直观。
在stackoverflow的问题中，还有一个高票回答是放在POST body里，这样符合规范吗？
