跳转至

RESTFul最佳实践（简译）

本指南需要对RESTful有基本的了解，不熟悉的人可以移步维基百科

首先一定要按照

GET ：获取数据
POST：新建数据
PUT：修改数据
DELETE：删除数据

还有理论上我们应该支持XML和JSON，但是让XML沉睡吧。

  1. 资源描述符（即API地址），要是名词而非动词形势

    例如：POST:api/portfolio/32/update,代表的是意思是修改ID为32的portfolio。但是这不符合REST，

    REST的做法是PUT:api/portfolio/32,用请求方法承载动作，资源描述符只是一个名词

    URL里面尽量避免出现api/portfolio?type=1&status=0这样的参数

  2. HTTP状态码

    请求响应回信息后，通常都会有一个HTTP Status,如果请求正确的话，这个status会是200，status 404大家应该都知道，资源未找到。所以为了统一处理响应信息服务器返回的状态都用status表示。

    注意这里的统一处理,我想大家都会见过服务器自定义一个字段，比如code，比如result，来返回请求状态。 注意这个状态是在响应body里面的，而不是header里面的status。 所以一旦服务器出错了，就无法返回正确的body，body里面的code或者result也无法返回， 这样客户端程序就需要对header里面的status做错误捕获，这样错误捕获程序要监控两个地方，header里面的status，body里面的code。 其实我原来也是这么做的，所以为了统一处理，header的status是最好的办法。

    HTTP状态码继续移步 维基百科

  3. 对于POST创建资源后应该返回的是数据还是地址？

    通常API习惯中，利用POST创建完数据后，直接返回创建的数据，客户端就可以直接拿来处理了。有没有考虑另外一种可能。POST完之后，返回header status 301,还有header：location:api/portolio/[newid]

    虽然客户端需要再发起一个新的请求来得到数据。但是通常情况下，当请求一个资源数据的时候，这个数据都是被加工过的。比如被附加上分类数据，被附加上评论数据等等。而POST完之后返回的数据是什么样的，就要拼人品了。

  4. 分页

    实例:GET:api/portfolio/?offset=0&limit=25

    上面是请求portfolio的数据。从0开始，也就是从第一行开始，查出下25条数据

    服务器返回的除了包含这25条数据之外，header里面还会包含Content-Range: items 0-24/66

    这里面表示的返回的条目是0到24的（注意这里是zero-based，也就是像数组一样，已0开始的）25条数据。斜杠后面表示这个请求最多可返回的数量。

  5. 排序筛选

    筛选实例:api/portfolio/?filter=”name::john|city_id::3”

    这条请求的意思是查询名字为john，城市ID为3的portfolio

    很简单的，就是用|分割不同的查询条件。：：代表等于的意思

    排序实例:api/portfolio/?sort=”name|-create_date”

    这条请求的意思是先按照名字正序，然后按照创建日期倒序

附上原版PDF